Facehash

Deterministic avatar generation for Kotlin Multiplatform

Generate unique, deterministic avatar faces from any string. The same input always produces the same face, making it perfect for user avatars, identicons, or any scenario requiring consistent visual identifiers.

Features

• Deterministic generation - Same string always produces the same face
• 4 face types - Round, Cross, Line, and Curved eye styles
• 3D rotation effects - Configurable intensity levels for depth
• Background variants - Gradient overlay or solid color
• Interactive hover - Face "looks straight" on mouse hover
• Initial letter display - Optional first letter below the face
• Custom color palettes - Use your own colors or the default Tailwind palette
• Custom mouth renderer - Replace the initial with any composable

Installation

Gradle (Version Catalog)

Add to your libs.versions.toml:

[versions]
facehash = "1.0.0"

[libraries]
facehash = { module = "im.nmds.oss:facehash", version.ref = "facehash" }

Then in your module's build.gradle.kts:

dependencies {
    implementation(libs.facehash)
}

Direct Dependency

dependencies {
    implementation("im.nmds.oss:facehash:1.0.0")
}

Note: Maven coordinates are placeholders. Update with actual published coordinates when available.

Quick Start

import im.nmds.oss.facehash.Facehash

@Composable
fun UserAvatar() {
    Facehash(name = "Alice")
}

Different names generate different faces:

Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
    Facehash(name = "Alice")
    Facehash(name = "Bob")
    Facehash(name = "Charlie")
}

API Reference

Facehash Composable

@Composable
fun Facehash(
    name: String,
    modifier: Modifier = Modifier,
    size: Dp = FacehashDefaults.DEFAULT_SIZE,
    variant: Variant = FacehashDefaults.DEFAULT_VARIANT,
    intensity3d: Intensity3D = FacehashDefaults.DEFAULT_INTENSITY,
    interactive: Boolean = true,
    showInitial: Boolean = true,
    colors: List<Color> = FacehashDefaults.DEFAULT_COLORS,
    onRenderMouth: (@Composable () -> Unit)? = null
)

Parameter	Type	Default	Description
name	String	required	Input string for deterministic face generation
modifier	Modifier	Modifier	Standard Compose modifier
size	Dp	40.dp	Avatar size
variant	Variant	GRADIENT	Background style
intensity3d	Intensity3D	DRAMATIC	3D rotation effect level
interactive	Boolean	true	Enable hover interaction
showInitial	Boolean	true	Show first letter below face
colors	List<Color>	Tailwind palette	Custom color palette
onRenderMouth	@Composable (() -> Unit)?	null	Custom mouth renderer

Configuration Options

Intensity3D

Controls the 3D rotation depth effect:

Value	Description
NONE	No 3D effect, face is flat
SUBTLE	Slight rotation (5° range)
MEDIUM	Moderate rotation (10° range)
DRAMATIC	Strong rotation (15° range) - default

Variant

Controls the background style:

Value	Description
GRADIENT	Adds a radial gradient overlay - default
SOLID	Plain background color

FacehashDefaults

Access default values programmatically:

FacehashDefaults.DEFAULT_SIZE      // 40.dp
FacehashDefaults.DEFAULT_INTENSITY // Intensity3D.DRAMATIC
FacehashDefaults.DEFAULT_VARIANT   // Variant.GRADIENT
FacehashDefaults.DEFAULT_COLORS    // Tailwind color palette
FacehashDefaults.FALLBACK_COLOR    // Pink fallback

Examples

Size Variations

Facehash(name = "Alice", size = 32.dp)
Facehash(name = "Alice", size = 48.dp)
Facehash(name = "Alice", size = 64.dp)

3D Intensity Levels

Facehash(name = "Bob", intensity3d = Intensity3D.NONE)
Facehash(name = "Bob", intensity3d = Intensity3D.SUBTLE)
Facehash(name = "Bob", intensity3d = Intensity3D.MEDIUM)
Facehash(name = "Bob", intensity3d = Intensity3D.DRAMATIC)

Custom Colors

Facehash(
    name = "Charlie",
    colors = listOf(
        Color(0xFF6366F1), // Indigo
        Color(0xFF8B5CF6), // Violet
        Color(0xFFEC4899)  // Pink
    )
)

Solid Background

Facehash(
    name = "Diana",
    variant = Variant.SOLID
)

Avatar Grid

val names = listOf("Alice", "Bob", "Charlie", "Diana", "Eve", "Frank")

LazyVerticalGrid(columns = GridCells.Fixed(3)) {
    items(names) { name ->
        Facehash(name = name, size = 56.dp)
    }
}

Custom Mouth Renderer

Facehash(
    name = "Eve",
    showInitial = false,
    onRenderMouth = {
        Icon(
            imageVector = Icons.Default.Verified,
            contentDescription = null,
            tint = Color.Black,
            modifier = Modifier.size(12.dp)
        )
    }
)

Platform Support

Platform	Target	Minimum Version
Android	androidTarget	SDK 24
iOS	iosArm64, iosSimulatorArm64	-
Desktop	jvm	JVM 11
Web	js, wasmJs	Modern browsers

Credits

This library is a Kotlin Multiplatform port of the facehash library from Cossistant, originally implemented in React/TypeScript.