---
title: TextInput
description: TextInput element api.
---
import SlintProperty from '@slint/common-files/src/components/SlintProperty.astro';
import Link from '@slint/common-files/src/components/Link.astro';

The `TextInput` is a lower-level item that shows text and allows entering text.
You should probably not use this directly, but instead use the <Link type="LineEdit" /> or <Link type="TextEdit" /> component.

When not part of a layout, its width and height defaults to 100% of the parent element.

The `TextInput` does not scroll automatically when the cursor is outside of the visible area.
This is the responsibility of the enclosing widget to ensure using the `cursor-position-changed` callback.

## Example

```slint playground
export component Example inherits Window {
    width: 270px;
    height: 40px;
    Rectangle {
        clip: true;

        TextInput {
            text: "Edit me";
            width: max(parent.width, self.preferred-width);
            vertical-alignment: center;

            private property <length> margin: 1rem;
            cursor-position-changed(cursor-position) => {
                if cursor-position.x + self.x < margin {
                    self.x = - cursor-position.x + margin;
                } else if cursor-position.x + self.x > parent.width - margin - self.text-cursor-width {
                    self.x = parent.width - cursor-position.x - margin - self.text-cursor-width;
                }
            }
        }
    }
}
```

## Properties

### color
<SlintProperty propName="color" typeName="brush" defaultValue="depends on the style">
The color of the text.
</SlintProperty>

### font-family
<SlintProperty propName="font-family" typeName="string">
The name of the font family selected for rendering the text.
</SlintProperty>

### font-size
<SlintProperty propName="font-size" typeName="length">
The font size of the text.
</SlintProperty>

### font-weight
<SlintProperty propName="font-weight" typeName="int">
The weight of the font. The values range from 100 (lightest) to 900 (thickest). 400 is the normal weight.
</SlintProperty>

### font-italic
<SlintProperty propName="font-italic" typeName="bool" defaultValue="false">
Whether or not the font face should be drawn italicized or not.
</SlintProperty>

### font-metrics
<SlintProperty propName="font-metrics" typeName="struct" structName="FontMetrics">
The design metrics of the font scaled to the font pixel size used by the element.
</SlintProperty>

### has-focus
<SlintProperty propName="has-focus" typeName="bool" propertyVisibility="out">
`TextInput` sets this to `true` when it's focused. Only then it receives <Link type="KeyEvent"/>s.
</SlintProperty>

### horizontal-alignment
<SlintProperty propName="horizontal-alignment" typeName="enum" enumName="TextHorizontalAlignment">
The horizontal alignment of the text.
</SlintProperty>

### input-type
<SlintProperty propName="input-type" typeName="enum" enumName="InputType" defaultValue="text">
 Use this to configure `TextInput` for editing special input, such as password fields.
</SlintProperty>

### letter-spacing
<SlintProperty propName="letter-spacing" typeName="length" defaultValue="0">
The letter spacing allows changing the spacing between the glyphs. A positive value increases the spacing and a negative value decreases the distance.
</SlintProperty>

### page-height
<SlintProperty propName="page-height" typeName="length">
The height of the page used to compute how much to scroll when the user presses page up or page down.
</SlintProperty>

### read-only
<SlintProperty propName="read-only" typeName="bool" defaultValue="false">
When set to `true`, text editing via keyboard and mouse is disabled but selecting text is still enabled as well as editing text programmatically.
</SlintProperty>

### selection-background-color
<SlintProperty propName="selection-background-color" typeName="color">
The background color of the selection.
</SlintProperty>

### selection-foreground-color
<SlintProperty propName="selection-foreground-color" typeName="color">
The foreground color of the selection.
</SlintProperty>

### single-line
<SlintProperty propName="single-line" typeName="bool" defaultValue="true">
When set to `true`, the text is always rendered as a single line, regardless of new line separators in the text.
</SlintProperty>

### text-cursor-width
<SlintProperty propName="text-cursor-width" typeName="length" defaultValue="provided at run-time by the selected widget style">
The width of the text cursor.
</SlintProperty>

### text
<SlintProperty propName="text" typeName="string" defaultValue='""'>
The text rendered and editable by the user.
</SlintProperty>

### vertical-alignment
<SlintProperty propName="vertical-alignment" typeName="enum" enumName="TextVerticalAlignment">
The vertical alignment of the text.
</SlintProperty>

### wrap
<SlintProperty propName="wrap" typeName="enum" enumName="TextWrap" defaultValue="no-wrap">
The way the text input wraps. Only makes sense when `single-line` is false.
</SlintProperty>

## Functions

### focus()
Call this function to focus the text input and make it receive future keyboard events.

### clear-focus()
Call this function to remove keyboard focus from this `TextInput` if it currently has the focus. See also <Link type="FocusHandling" />.

### set-selection-offsets(int, int)
Selects the text between two UTF-8 offsets.

### select-all()
Selects all text.

### clear-selection()
Clears the selection.

### copy()
Copies the selected text to the clipboard.

### cut()
Copies the selected text to the clipboard and removes it from the editable area.

### paste()
Pastes the text content of the clipboard at the cursor position.

## Callbacks

### accepted()
Invoked when the enter key is pressed.

### cursor-position-changed(Point)
The cursor was moved to the new (x, y) position
described by the `Point` argument.

### edited()
Invoked when the text has changed because the user modified it.

### key-pressed(KeyEvent) -> EventResult
Invoked when a key is pressed, the argument is a <Link type="KeyEvent" /> struct. Use this callback to
handle keys before `TextInput` does. Return `accept` to indicate that you've handled the event, or return
`reject` to let `TextInput` handle it.

### key-released(KeyEvent) -> EventResult
Invoked when a key is released, the argument is a <Link type="KeyEvent" /> struct. Use this callback to
handle keys before `TextInput` does. Return `accept` to indicate that you've handled the event, or return
`reject` to let `TextInput` handle it.


## Accessibility

By default, `TextInput` elements have the following accessibility properties set:

 - `accessible-role: text-input;`
 - `accessible-value: text;`
 - `accessible-enabled: enabled;`
 - `accessible-read-only: read-only; `
