Headless forms for
Jetpack Compose

Installation

Add the dependencies and the KSP plugin to your module's build.gradle.kts.

plugins {
    id("com.google.devtools.ksp")
}

dependencies {
    implementation("io.github.wassimbeltaief:formidable-core:2.0.0")
    implementation("io.github.wassimbeltaief:formidable-compose:2.0.0")
    ksp("io.github.wassimbeltaief:formidable-ksp:2.0.0")
}

Quick start

Two steps: annotate a data class, wire the fields in Compose.

@FormSchema
data class LoginForm(
    @Field(label = "Email", hint = "you@example.com")
    @Email("Please enter a valid email")
    val email: String = "",

    @Field(label = "Password", hint = "At least 8 characters")
    @MinLength(8, "Password must be at least 8 characters")
    val password: String = "",
)

@Composable
fun LoginScreen() {
    val controller = remember { LoginFormController() }
    val emailState by controller.email.collectAsState()
    val passwordState by controller.password.collectAsState()
    val isValid by controller.isValid.collectAsState()

    Formidable {
        StringField(
            state = emailState,
            onValueChange = { controller.updateEmail(it) },
            onFocusLost = { controller.touchEmail() },
        )
        StringField(
            state = passwordState,
            onValueChange = { controller.updatePassword(it) },
            onFocusLost = { controller.touchPassword() },
            config = {
                keyboardType = KeyboardType.Password
                visualTransformation = PasswordVisualTransformation()
            },
        )
        Button(onClick = { /* submit */ }, enabled = isValid) {
            Text("Login")
        }
    }
}

Three rendering modes

Every field supports three call forms. Start with auto-render, reach for config overrides when needed, drop to headless for full control.

StringField(
    state = emailState,
    onValueChange = { controller.updateEmail(it) },
    onFocusLost = { controller.touchEmail() },
)

BooleanField(
    state = acceptTermsState,
    onCheckedChange = { controller.updateAcceptTerms(it) },
    onFocusLost = { controller.touchAcceptTerms() },
)

// Password field — override keyboard type and visual transformation
StringField(
    state = passwordState,
    onValueChange = { controller.updatePassword(it) },
    onFocusLost = { controller.touchPassword() },
    config = {
        visualTransformation = PasswordVisualTransformation()
        keyboardType = KeyboardType.Password
    },
)

// Enum field rendered as radio group instead of dropdown
EnumField(
    state = contactMethodState,
    options = ContactMethod.entries,
    onSelect = { controller.updateContactMethod(it) },
    config = { style = FieldStyle.Picker.RadioGroup },
)

// Switch row instead of checkbox row
BooleanField(
    state = notificationsState,
    onCheckedChange = { controller.updateNotifications(it) },
    onFocusLost = { controller.touchNotifications() },
    config = { style = FieldStyle.Toggle.SwitchRow },
)

StringField(
    state = emailState,
    onValueChange = { controller.updateEmail(it) },
    onFocusLost = { controller.touchEmail() },
) {
    OutlinedTextField(
        value = value,
        onValueChange = onValueChange,
        modifier = modifier.fillMaxWidth(),
        label = { Text(label) },
        isError = showError,
        supportingText = if (showError) { { Text(errorMessage ?: "") } } else null,
        keyboardOptions = keyboardOptions,
        keyboardActions = keyboardActions,
    )
}

FieldStyle reference

Pass style = FieldStyle.* inside a config = { } block to change the rendered widget.

FieldScope

When using the headless trailing-lambda API, every field block receives a typed scope with these properties.

Annotations

All annotations live in formidable-core.

Async validation

Implement AsyncFieldValidator<T> and attach it with @AsyncValidation. The controller debounces automatically and exposes isValidating for a loading indicator.

class UniqueUsernameValidator : AsyncFieldValidator<String> {
    override suspend fun validate(value: String): ValidationResult {
        val taken = api.checkUsername(value)
        return if (taken)
            ValidationResult.Invalid(listOf("Username '$value' is already taken"))
        else
            ValidationResult.Valid
    }
}

@FormSchema
data class SignUpForm(
    @Field(label = "Username")
    @NotBlank("Username is required")
    @AsyncValidation(UniqueUsernameValidator::class)
    val username: String = "",
)

Use config = { } to override the supporting text and trailing icon while keeping auto-rendering. usernameState is read from the outer composable's collectAsState() — the config lambda stores composable values but is not itself composable.

val usernameState by controller.username.collectAsState()

StringField(
    state = usernameState,
    onValueChange = { controller.updateUsername(it) },
    onFocusLost = { controller.touchUsername() },
    config = {
        supportingText = when {
            usernameState.isValidating -> { { Text("Checking availability…") } }
            usernameState.showError    -> { { Text(usernameState.errorMessage ?: "") } }
            else -> null
        }
        trailingIcon = if (usernameState.isValidating) {
            { CircularProgressIndicator(Modifier.size(20.dp)) }
        } else null
    },
)

Cross-field validation

Use @MatchField to require a field to match another — the classic password confirmation pattern. The generated controller re-validates the dependent field automatically whenever the source changes.

@FormSchema
data class SignUpForm(
    @Field(label = "Password")
    @MinLength(8)
    val password: String = "",

    @Field(label = "Confirm password")
    @MatchField("password", "Passwords do not match")
    val confirmPassword: String = "",
)