Text fields

Text fields let users enter and edit text.

On this page

Specifications references
Accessibility
Variants
- Text field #
  - Jetpack Compose
    - OdsTextField API #
- Password text field #
  - Jetpack Compose
    - OdsPasswordTextField API #
Extras
- Character counter #
  - Jetpack Compose
    - OdsTextFieldCharacterCounter #
Custom theme configuration

Specifications references

Accessibility

Please follow accessibility criteria for development.

Android’s text field component APIs support both label text and helper text for informing the user as to what information is requested for a text field.

Variants

Text field #

A text field can be filled or outlined.
The outlined version is more accessible in term of contrast. This is the reason why Orange text fields are outlined.

TextField outlined light
TextField outlined dark

TextField filled light
TextField filled dark

Jetpack Compose

To add a text field in your composable screen you can use the OdsTextField composable as follow:

var text by rememberSaveable { mutableStateOf("") }
OdsTextField(
    leadingIcon = OdsTextField.LeadingIcon(
        painterResource(id = R.drawable.ic_heart),
        "Like"
    ) { doSomething() },
    trailing = OdsTextField.TrailingText(text = "units"), // It can be one of the provided `OdsTextField.Trailing`. See more information below.
    enabled = true,
    readOnly = false,
    isError = false,
    errorMessage = "Error message",
    value = text,
    onValueChange = { text = it },
    label = "Label",
    placeholder = "Placeholder",
    visualTransformation = VisualTransformation.None,
    keyboardOptions = KeyboardOptions.Default,
    keyboardActions = KeyboardActions(),
    singleLine = false,
    maxLines = Int.MAX_VALUE,
    characterCounter = OdsTextFieldCharacterCounter(
        characterCount = characterCount,
        maxCharacterCount = 20,
        enabled = true
    )
)

The library provides several OdsTextField.Trailing that you can use as trailing element for text field:

OdsTextField.TrailingIcon: Displays an icon as trailing element
OdsTextField.TrailingText: Displays a text as trailing element

Note: You will find more information about the character counter in Extras

OdsTextField API #

Parameter	Default value	Description
`value: String`		Input text to be shown in the text field
`onValueChange: (String) -> Unit`		Callback that is triggered when the input service updates the text. An updated text comes as a parameter of the callback.
`modifier: Modifier`	`Modifier`	Modifier applied to this text field
`trailing: OdsTextField.Trailing?`	`null`	Trailing element to display at the end of the text field
`enabled: Boolean`	`true`	Controls the enabled state of the text field. When `false`, the text field will be neither editable nor focusable, the input of the text field will not be selectable, visually text field will appear in the disabled UI state.
`readOnly: Boolean`	`false`	Controls the editable state of the text field. When `true`, the text field can not be modified, however, a user can focus it and copy text from it. Read-only text fields are usually used to display pre-filled forms that user can not edit.
`label: String?`	`null`	Label to be displayed inside or outside the text field. The default text style used is `OdsTypography.bodyS` when the text field is in focus and `OdsTypography.titleM` when the text field is not in focus.
`placeholder: String?`	`null`	Placeholder to be displayed when the text field is in focus and the input text is empty. The default text style for internal `Text` is `OdsTypography.titleM`.
`leadingIcon: OdsTextField.LeadingIcon?`	`null`	Icon displayed at the beginning of the text field container
`isError: Boolean`	`false`	Indicates if the text field’s current value is in error state. If set to `true`, the text field outline and the error message will be displayed in error color.
`errorMessage: String?`	`null`	Message displayed below the text field when it is in error
`visualTransformation: VisualTransformation`	`VisualTransformation.None`	Transforms the visual representation of the input value. For example, you can use `PasswordVisualTransformation` to create a password text field. By default no visual transformation is applied.
`keyboardOptions: KeyboardOptions`	`KeyboardOptions.Default`	Software keyboard options that contains configuration such as `KeyboardType` and `ImeAction`
`keyboardActions: KeyboardActions`	`KeyboardActions()`	When the input service emits an IME action, the corresponding callback is called. Note that this IME action may be different from what you specified in `KeyboardOptions.imeAction`.
`singleLine: Boolean`	`false`	When set to `true`, this text field becomes a single horizontally scrolling text field instead of wrapping onto multiple lines. The keyboard will be informed to not show the return key as the `ImeAction`. Note that `maxLines` parameter will be ignored as the maxLines attribute will be automatically set to 1.
`maxLines: Int`	`Int.MAX_VALUE`	Maximum number of visible lines. Should be equal or greater than 1. Note that this parameter will be ignored and instead maxLines will be set to 1 if `singleLine` is set to `true`.
`characterCounter:` OdsTextFieldCharacterCounter`?`	`null`	Character counter displayed below the text field

Password text field #

Password text field is a text field implementation that includes password visual transformation and optional visualisation icon.

TextField outlined password light
TextField outlined password dark

TextField filled password light
TextField filled password dark

Jetpack Compose

To add a password text field in your composable screen you can use the OdsPasswordTextField composable as follow:

var text by rememberSaveable { mutableStateOf("") }
OdsPasswordTextField(
    enabled = true,
    readOnly = false,
    isError = false,
    errorMessage = "Error message",
    value = text,
    onValueChange = { text = it },
    label = "Label",
    placeholder = "Placeholder",
    visualisationIcon = true,
    keyboardOptions = KeyboardOptions.Default,
    keyboardActions = KeyboardActions(),
    characterCounter = OdsTextFieldCharacterCounter(
        characterCount = characterCount,
        maxCharacterCount = TextFieldMaxCharacterCount,
        enabled = enabled
    )
)

Note: This composable relies on OdsTextField in order to keep homogeneity in each application. Its appearance (outlined or filled) is inherited from text fields style configuration. See text field section if you want to change it in your custom theme.

OdsPasswordTextField API #

Parameter	Default value	Description
`value: String`		Input text to be shown in the text field
`onValueChange: (String) -> Unit`		Callback that is triggered when the input service updates the text. An updated text comes as a parameter of the callback.
`modifier: Modifier`	`Modifier`	Modifier applied to this text field
`enabled: Boolean`	`true`	Controls the enabled state of the text field. When `false`, the text field will be neither editable nor focusable, the input of the text field will not be selectable, visually text field will appear in the disabled UI state.
`readOnly: Boolean`	`false`	Controls the editable state of the text field. When `true`, the text field can not be modified, however, a user can focus it and copy text from it. Read-only text fields are usually used to display pre-filled forms that user can not edit.
`label: String?`	`null`	Label to be displayed inside or outside the text field. The default text style used is `OdsTypography.bodyS` when the text field is in focus and `OdsTypography.titleM` when the text field is not in focus.
`placeholder: String?`	`null`	Placeholder to be displayed when the text field is in focus and the input text is empty. The default text style for internal `Text` is `OdsTypography.titleM`.
`visualisationIcon: Boolean`	`true`	Controls the display of the eye icon to allow showing/hiding password
`isError: Boolean`	`false`	Indicates if the text field’s current value is in error state. If set to `true`, the text field outline and the error message will be displayed in error color.
`errorMessage: String?`	`null`	Message displayed below the text field when it is in error
`keyboardOptions: KeyboardOptions`	`KeyboardOptions.Default`	Software keyboard options that contains configuration such as `KeyboardType` and `ImeAction`
`keyboardActions: KeyboardActions`	`KeyboardActions()`	When the input service emits an IME action, the corresponding callback is called. Note that this IME action may be different from what you specified in `KeyboardOptions.imeAction`.
`characterCounter:` OdsTextFieldCharacterCounter`?`	`null`	Character counter displayed below the text field

Extras

Character counter #

TextField character counter light
TextField character counter dark

Jetpack Compose

In each TextField component, you can use the characterCounter parameter to add a character counter if there is a restriction on the number of characters in a field.
It will be placed properly below the text field, end aligned.

Use the OdsTextFieldCharacterCounter class for this behavior as shown below:

OdsTextFieldCharacterCounter(
    modifier = Modifier.align(Alignment.End),
    characterCount = characterCount,
    maxCharacterCount = 20,
    enabled = true
)

Be careful, the limitation behavior should be managed by yourself in the onValueChange method of the text field:

if (text.length <= TextFieldMaxCharacterCount) {
    value = text
}

OdsTextFieldCharacterCounter #

Parameter	Default value	Description
`characterCount: Int`		Text field current characters count.
`maxCharacterCount: Int`		Maximum number of characters to display in the counter. Note: the limitation behavior should be managed by yourself in the `onValueChange` method of the text field.
`enabled: Boolean`	`true`	Controls the enable state of the counter. If set to `false` the text will be displayed in disabled color.

Custom theme configuration

You can override the default display of text fields in your custom theme by overriding the textFieldStyle attribute as below:

override val components: OdsComponentsConfiguration
    get() = object : OdsComponentsConfiguration() {
        override val textFieldStyle: ComponentStyle
            get() = ComponentStyle.Filled
    }