# Textfield

An **Outlined Text Field** is a primary input component that allows users to enter and edit text. It features a visible border (outline) that clearly defines the hit area and structure of the input field, making it immediately recognizable as an interactive element.

> For deeper reference, see the [Material Design](https://m3.material.io/components/text-fields/overview) guidelines on text fields.

***

## When to Use

**Use** an Outlined Text Field for:

* Standard data entry forms (e.g., sign-up flows, shipping addresses)
* Short inputs like usernames, email addresses, and passwords
* Multi-line text areas (e.g., a "comments" section)

**Avoid** an Outlined Text Field when:

* The input needs to blend seamlessly into a surrounding layout (e.g., a search bar in a header)
* The UI space is too tight and the visual weight of the outline creates clutter

***

## Basic Example

| Slot            | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| `value`         | The current text string to display in the input field.         |
| `onValueChange` | The callback invoked when the user types or modifies the text. |

<figure><img src="/files/uQ6NzosLRqIE3lkI7w48" alt="Textfield example image"><figcaption></figcaption></figure>

```kotlin
var email by remember { mutableStateOf("") }

OutlinedTextField(
    value = email,
    onValueChange = { email = it },
    label = { Text("Email Address") },
    placeholder = { Text("example@domain.com") }
)
```

***

## Styling

Textfield exposes several parameters to customize its appearance and layou

### Parameters

| Parameter              | Type                        | Default                                       | Description                                                                           |
| ---------------------- | --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------- |
| `modifier`             | `Modifier`                  | `Modifier`                                    | Applied to the outer layout of the text field.                                        |
| `enabled`              | `Boolean`                   | `true`                                        | Controls interactive state. When `false`, the field ignores input.                    |
| `readOnly`             | `Boolean`                   | `false`                                       | When `true`, the field cannot be modified but can still be focused.                   |
| `textStyle`            | `TextStyle?`                | `null`                                        | The typography style applied to the typed input text.                                 |
| `label`                | `@Composable (() -> Unit)?` | `null`                                        | Text that sits inside the field and floats to the border when focused.                |
| `placeholder`          | `@Composable (() -> Unit)?` | `null`                                        | Hint text that appears when the field is empty and focused.                           |
| `leadingIcon`          | `@Composable (() -> Unit)?` | `null`                                        | An optional icon displayed at the start (left) of the text field.                     |
| `trailingIcon`         | `@Composable (() -> Unit)?` | `null`                                        | An optional icon displayed at the end (right) of the text field.                      |
| `description`          | `@Composable (() -> Unit)?` | `null`                                        | Helper or error text displayed beneath the field.                                     |
| `isError`              | `Boolean`                   | `false`                                       | Visually highlights the field (border, label, etc.) to indicate a validation failure. |
| `visualTransformation` | `VisualTransformation`      | `VisualTransformation.None`                   | Alters the visual presentation of text (e.g., masking passwords).                     |
| `keyboardOptions`      | `KeyboardOptions`           | `KeyboardOptions.Default`                     | Configures the software keyboard (e.g., number pad vs. text).                         |
| `keyboardActions`      | `KeyboardActions`           | `KeyboardActions.Default`                     | Defines what software keyboard action keys (like "Done") do.                          |
| `singleLine`           | `Boolean`                   | `false`                                       | Forces the input to remain on one horizontal line.                                    |
| `maxLines`             | `Int`                       | `Int.MAX_VALUE`                               | Maximum visible lines before the internal text starts scrolling vertically.           |
| `minLines`             | `Int`                       | `1`                                           | Minimum height of the text field, defined by number of visible lines.                 |
| `shape`                | `Shape`                     | `TextFieldDefaults.defaultTextFieldShape`     | The geometric shape applied to the boundary line of the text field.                   |
| `borderWidth`          | `OutlinedBorderWidth`       | `TextFieldDefaults.defaultBorderWidth()`      | The thickness of the outline border across different states.                          |
| `textFieldColors`      | `TextFieldColors`           | `TextFieldDefaults.outlinedTextFieldColors()` | Colors for all text, backgrounds, and borders across all states.                      |

***

### Password with Error Handling

The `leadingIcon`, `trailingIcon`, and `description` slots combine to create complex inputs with real-time validation feedback — ideal for password fields.

<figure><img src="/files/nuqpvXX9kk1HgWVT9UiC" alt=""><figcaption></figcaption></figure>

```kotlin
var password by remember { mutableStateOf("") }
val isError = password.isNotEmpty() && password.length < 8

OutlinedTextField(
    value = password,
    onValueChange = { password = it },
    label = { Text("Password") },
    leadingIcon = {
        Icon(imageVector = PhIcons.Regular.Lock, contentDescription = null)
    },
    trailingIcon = {
        Icon(imageVector = PhIcons.Regular.Eye, contentDescription = "Toggle visibility")
    },
    description = {
        if (isError) {
            Text("Password must be at least 8 characters.")
        } else {
            Text("Use a secure, unique password.")
        }
    },
    isError = isError,
    visualTransformation = PasswordVisualTransformation(),
    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password)
)
```

### Multi-line Text Area

To create a text area suitable for notes or comments, set `singleLine = false` and provide a higher `minLines` value. This ensures the field starts out tall, signalling to users that a longer response is expected.

<figure><img src="/files/6f6b29G3lCwyaq5ZCpYL" alt="Custom Textfield example image"><figcaption></figcaption></figure>

````kotlin
var bio by remember { mutableStateOf("") }

OutlinedTextField(
    value = bio,
    onValueChange = { bio = it },
    label = { Text("About Me") },
    singleLine = false,
    minLines = 4,
    maxLines = 10,
    modifier = Modifier.fillMaxWidth()
)
```s
````


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kore-1.gitbook.io/kore/documentation/inputs-and-controls/textfield.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.