# Text Area (lv_textarea) (/widgets/textarea)
Overview [#overview]
A Text Area is a [base widget](/widgets/base_widget) holding a
[Label](/widgets/label) and a cursor. You can add or remove text and
characters. Long lines wrap, and when the text gets too long the area
becomes scrollable.
One-line mode and password mode are also supported.
Adding text [#adding-text]
You can insert text or characters to the current cursor's position with:
*
*
To add wide characters like `'á'`, `'ß'` or CJK characters, use
.
replaces all existing text
with "New text".
Placeholder text [#placeholder-text]
Placeholder text is text that is displayed when the Text Area is empty. This can be
a handy way to provide the end user with a hint about what to type there.
Specify placeholder text using
.
Delete character [#delete-character]
To delete the character to the left of the current cursor position, use
.
To delete to the right, use
Moving the cursor [#moving-the-cursor]
The cursor position can be modified programmatically using
where `cursor_pos` is
the zero-based index of the character the cursor should be placed in front of.
can be passed to mean "after the
last character"
You can move the cursor one character-position (or line) at a time with
*
*
*
*
If is applied, the
cursor will jump to the position where the Text Area was clicked.
Hiding the cursor [#hiding-the-cursor]
The cursor is normally always visible. It can be a good idea to style it
to be visible only in state. See [Styles](/common-widget-features/styles)
for more information about how to do this.
One-line mode [#one-line-mode]
The Text Area can be configured to keep all text on a single line with
. In this mode:
* the height is set automatically to show only one line,
* line break characters are ignored, and
* word wrap is disabled.
Password mode [#password-mode]
The Text Area supports password mode which can be enabled with
.
By default, if the [•` (`Bullet,
U+2022](https://www.fileformat.info/info/unicode/char/2022/index.htm))
character exists in the font, the entered characters are converted to it after
a configurable delay after each new character is entered. If `•` does not
exist in the font, `*` will be used. You can override the default
"masking" character with
where `str` is a NUL-terminated C string. Example:
```c title=" " lineNumbers=1
lv_textarea_set_password_bullet(textarea, "x");
```
In password mode returns the actual
text entered, not the bullet characters.
The visibility time can be adjusted with in `lv_conf.h`.
Accepted characters [#accepted-characters]
You can set a list of accepted characters with
or
where `list` is a
pointer to a NUL-terminated string, or NULL to accept all characters. Characters
entered not in this list will be ignored.
```c title=" " lineNumbers=1
lv_textarea_set_accepted_chars(textarea, "0123456789.+-");
```
Max text length [#max-text-length]
The maximum number of characters can be limited using
.
Very long text [#very-long-text]
For text exceeding \~20k characters, enable in
`lv_conf.h` to improve scrolling and drawing performance by caching vertical
position data. It is set to `1` by default.
Selecting text [#selecting-text]
Enable text selection with
.
Requires set to a non-zero value in `lv_conf.h`.
To manipulate the selection programmatically (`ta_label = lv_textarea_get_label(textarea)`):
* — whether selection is enabled.
* — whether text is currently selected.
* — clears the selection.
* — start index; pass for none.
* — end index (exclusive); pass for none.
* — gets start index.
* — gets end index.
Styling [#styling]
The Text Area exposes these parts, each styled independently with a named
style and a `selector`:
* The background of the Text Area; uses the
[typical background style properties](/common-widget-features/styles/overview) and the text related
style properties including `text_align` to align the text to the left,
right or center.
* The scrollbar that is shown when the text is
longer than its height.
* Determines the style of the [selected
text](/widgets/label). Only `text_color` and
`bg_color` style properties can be used. `bg_color` should be set
directly on the label of the Text Area.
* Marks the position where the characters are
inserted. The cursor's area is always the bounding box of the current
character. A block cursor can be created by adding a background color
and background opacity to 's style. To create
a "bar" cursor leave the cursor transparent and set a left border. The
`anim_time` style property sets the cursor's blink time.
* Unique to Text Area; allows styling
the [placeholder text](/widgets/textarea).
Events [#events]
* Sent just before a character or text is
inserted. The event parameter is the text about to be inserted. From the
handler you can call
to replace it, or pass `""` to skip the insertion. The buffer must stay
valid until the current `lv_timer_handler()` call returns — don't pass
a stack-allocated string.
* Sent when the content of the Text Area
has changed.
* Sent when is
pressed (or sent) to a one-line Text Area.
Learn more about [Events](/common-widget-features/events) emitted by all Widgets.
Keys [#keys]
* `LV_KEY_UP/DOWN/LEFT/RIGHT` Move the cursor
* `Any character` Add the character to the current cursor position
Learn more about [Keys](/main-modules/indev/keypad).