Skip to content

Component

TextField

A FormaUI text field — "Material 3 with better defaults" — one entry point covering both Material 3 text-field families via variant, with fully hoisted state.

dev.formaui.components.textfield

outlinedfilled

Preview

This toggle is site chrome only — the preview has its own light/dark switch inside.

Live preview

Live preview — ~37 MB development build

Usage

var amount by remember { mutableStateOf("") }
FormaTextField(
    value = amount,
    onValueChange = { amount = it },
    label = "Amount",
    helperText = "Available balance: $5,000.00",
    singleLine = true,
)

FormaTextField

One entry point for both Material 3 text-field families (outlined and filled), with hoisted value state and helper/error supporting text on one line below the field.

valuerequiredTypeStringDefaultrequiredDescriptionThe current text to display.
onValueChangerequiredType(String) -> UnitDefaultrequiredDescriptionCalled with the updated text as the user edits. The caller must hoist and persist the new value for it to appear.
modifierTypeModifierDefaultModifierDescriptionThe Modifier applied to the field.
variantTypeFormaTextFieldVariantDefaultFormaTextFieldVariant.OutlinedDescriptionThe container style (defaults to FormaTextFieldVariant.Outlined).
enabledTypeBooleanDefaulttrueDescriptionWhether the field is editable and focusable. When false it is visually de-emphasised and ignores input.
readOnlyTypeBooleanDefaultfalseDescriptionWhether the field is read-only: it shows value and is focusable/selectable but not editable.
labelTypeString?DefaultnullDescriptionOptional floating label describing the field.
placeholderTypeString?DefaultnullDescriptionOptional placeholder shown while the field is empty.
leadingIconType@Composable (() -> Unit)?DefaultnullDescriptionOptional slot rendered at the start of the field.
trailingIconType@Composable (() -> Unit)?DefaultnullDescriptionOptional slot rendered at the end of the field.
isErrorTypeBooleanDefaultfalseDescriptionWhether the field is in the error state (error styling + accessibility signal).
helperTextTypeString?DefaultnullDescriptionOptional supporting text shown below the field when not in error.
errorTextTypeString?DefaultnullDescriptionOptional supporting text shown below the field while isError is true; takes precedence over helperText.
singleLineTypeBooleanDefaultfalseDescriptionWhether the field is constrained to a single line.
textStyleTypeTextStyleDefaultLocalTextStyle.currentDescriptionThe TextStyle applied to the input text (defaults to the ambient text style; pass FormaTheme.typography.numeric for tabular numeric entry).
visualTransformationTypeVisualTransformationDefaultVisualTransformation.NoneDescriptionTransforms the visual representation of value (e.g. password dots).
keyboardOptionsTypeKeyboardOptionsDefaultKeyboardOptions.DefaultDescriptionSoftware-keyboard configuration (type, IME action, capitalization).
keyboardActionsTypeKeyboardActionsDefaultKeyboardActions.DefaultDescriptionCallbacks for IME actions.
shapeTypeShape?DefaultnullDescriptionThe container shape. When null, the variant's sensible default is used (FormaTextFieldDefaults.outlinedShape for outlined, M3's shape for filled).
colorsTypeTextFieldColors?DefaultnullDescriptionThe field colors. When null, the M3 default colors for the variant are used.
interactionSourceTypeMutableInteractionSource?DefaultnullDescriptionThe MutableInteractionSource for observing/emitting interactions (focus, press). When null, one is remembered internally.

Supporting API

FormaTextFieldVariantenum
Container style of a FormaTextField: Outlined (default), Filled.
FormaTextFieldDefaultsobject
Defaults for FormaTextField: outlinedShape (FormaTheme.shapes.md).

Accessibility

isError applies error styling and surfaces the error state to accessibility services via the underlying M3 field; supply a contentDescription on any leading/trailing icon that conveys meaning.