# Text areas

> TextArea — multi-line input, scrolling and per-line icons.

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

# Text areas (`TextArea`)

`TextArea` is the **multi-line** field — same base (`TextInput`) as `TextField`, with line
wrapping, vertical scrolling and per-line icons.

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

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.style.*;   // TextAreaStyle (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());

      // Multi-line area: needs explicit height.
      // Here via container fraction (40% of the height); alternative: autoHeight in the style.
      TextArea obs = new TextArea().caption("Observações");
      add(0.4f, obs);

      // Label where the read content 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("Chars = " + obs.getText().length()));
      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
TextArea obs = new TextArea()
   .caption("Observações")
   .text("");
painel.add(0.5f, obs);   // takes up 50% of the container height (VerticalLayout)

// read the content:
String texto = obs.getText();
```

## Constructors and fluent API
| Member | Effect |
|---|---|
| `new TextArea()` / `new TextArea("texto")` | empty / with initial value |
| `.caption(String)` | caption |
| `.text(String)` / `setText(String)` | sets the content |
| `.rightIcons(Icon...)` | icons on the right, one per action line |
| `.rightIconAction(int linha, Action)` | action for a specific icon |
| `getText()` / `clearText()` | read / clear |
| `scrollToTop()` · `scrollToBottom()` · `scrollToLine(int)` | programmatic scrolling |

## Sizing
Unlike `TextField` (one-line height), `TextArea` needs an **explicit height** — give it a
fraction in a `VerticalLayout` or `autoHeight` in the style:
```java
obs.getStyle().autoHeight(Relative.ofFont(6f));   // ~6 lines tall
```

## Best practices
- Reserve enough height (container fraction or `autoHeight`) — otherwise it becomes a 1-line field.
- Use `scrollToBottom()` when appending text (e.g. log/chat) to keep the last line visible.

## Common mistakes
- Not setting a height → the area becomes tiny.
- Expecting horizontal scrolling — `TextArea` wraps lines; use `TextField` for a scrollable single line.

## See also
- [Text fields](/docs/ui/forms-and-input/text-fields) · [Focus and validation](/docs/ui/forms-and-input/focus-and-validation)
- Catalog: [TextArea](/docs/ui/widgets/textarea) · Reference: Chapter 14