# Text fields

> TextField — floating caption, icons, password with toggle and reading the value.

Source: https://crossfly.dev/docs/ui/forms-and-input/text-fields — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Text fields (`TextField`)

`TextField` is the **single-line** field. A fluent API for the essentials; fine-grained behavior comes from the
`TextFieldStyle`.

## Complete example (copy, paste and run)
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // TextFieldStyle (behavioral config)

/** Runnable main screen. Point the launcher (classname) and run: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // Name field with floating label
      TextField nome = new TextField().caption("Nome");
      nome.<TextFieldStyle>getStyle().floatingCaption(true);
      add(LAY_AUTO, nome);

      // Password field with show/hide button
      TextField senha = new TextField().caption("Senha");
      senha.<TextFieldStyle>getStyle()
         .mode(EditMode.PASSWORD)
         .passwordToggle(true);
      add(LAY_AUTO, senha);

      // Label where the read value will be displayed
      Label resultado = new Label("");
      add(LAY_AUTO, resultado);

      // There is NO per-key callback: read getText() on submit
      Button enviar = new Button("Enviar");
      enviar.onAction(c -> resultado.setText("Nome = " + nome.getText()));
      add(LAY_AUTO, enviar);
   }
}
```

> The snippets below show **only the core** (what goes inside `onShow()`). To run them, place them in the `MainWindow` skeleton above.

## Basic usage
```java
TextField nome = new TextField()
   .caption("Nome")                 // floating label
   .text("");                       // initial value
painel.add(LAY_AUTO, nome);

// read the value when needed (there is no per-key event):
Button enviar = new Button("Enviar");
enviar.onAction(c -> Debug.log("Nome = " + nome.getText()));
```

## Constructors and fluent API
| Member | Effect |
|---|---|
| `new TextField()` / `new TextField("texto")` | empty field / with initial value |
| `.caption(String)` | caption (floats when focused, if `floatingCaption`) |
| `.text(String)` / `setText(String)` | sets the value |
| `.leftIcon(Icon)` / `.rightIcon(Icon)` | icons at the ends |
| `.rightIcon(Icon, Action)` | clickable icon (e.g. clear) |
| `.keyboard(Keyboard)` | keyboard type (see [Masks and keyboards](/docs/ui/forms-and-input/masks-and-keyboards)) |
| `getText()` / `getTextWithoutMask()` | read value (with / without mask) |
| `clearText()` | clear |

## Floating caption
Enable it in the style (`floatingCaption`) — the caption rises on focus/fill:
```java
TextField email = new TextField().caption("E-mail");
email.<TextFieldStyle>getStyle().floatingCaption(true);
```

## Password with show/hide button
```java
TextField senha = new TextField().caption("Senha");
senha.<TextFieldStyle>getStyle()
   .mode(EditMode.PASSWORD)     // masks the characters
   .passwordToggle(true);       // adds the eye icon automatically
```
With `passwordToggle(true)`, the icon on the right toggles the visibility on its own.

## Action icon (e.g. clear)
```java
TextField busca = new TextField().caption("Buscar")
   .rightIcon(new MaterialIcon(""), c -> busca.clearText());  // "close"
```

## Best practices
- Read the value with `getText()` at submit time; for raw digits use `getTextWithoutMask()`.
- Configure behavior (`mode`, `maxLength`, `floatingCaption`) via the typed `getStyle()`
  (`campo.<TextFieldStyle>getStyle()...`).
- Limit the length with `.maxLength(n)` in the style when it makes sense.

## Common mistakes
- Looking for an `onChange`/`onTextChanged` — it **does not exist**; read `getText()` when you need to.
- Confusing `getText()` (with mask) with `getTextWithoutMask()` (without) when saving to the database.
- Setting `mode`/`mask` on the component — they are setters of the **style**.

## See also
- [Masks and keyboards](/docs/ui/forms-and-input/masks-and-keyboards) · [Focus and validation](/docs/ui/forms-and-input/focus-and-validation) · [Text areas](/docs/ui/forms-and-input/text-areas)
- Catalog: [TextField](/docs/ui/widgets/textfield) · Reference: Chapter 14