ts-basic-components-textinput.md

# TextInput

The **\<TextInput>** component provides single-line text input and is able to respond to input events.

> **NOTE**
>
> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.


## Required Permissions

None


## Child Components

Not supported


## APIs

TextInput(value?:{placeholder?: string | Resource, text?: string | Resource, controller?: TextInputController})

- Parameters
  | Name | Type | Mandatory | Default Value | Description |
  | -------- | -------- | -------- | -------- | -------- |
  | placeholder | string \|&nbsp;[Resource](../../ui/ts-types.md#resource-type) | No | - | Hint text displayed when there is no input. |
  | text             | string \| [Resource](../../ui/ts-types.md#resource-type)                                   | No    | -    | Current text input. |
  | controller<sup>8+</sup> | [TextInputController](#textinputcontroller8) | No | - | Text input controller. |


## Attributes

In addition to the universal attributes, the following attributes are supported.

| Name | Type | Default Value | Description |
| -------- | -------- | -------- | -------- |
| type | InputType | InputType.Normal | Input box type. |
| placeholderColor | Color | - | Placeholder text color. |
| placeholderFont | {<br/>size?: Length,<br/>weight?: number\|[FontWeight](ts-universal-attributes-text-style.md),<br/>family?: string,<br/>style?: [FontStyle](ts-universal-attributes-text-style.md)<br/>} | - | Placeholder text style.<br/>- **size**: font size. If the value is of the number type, the unit fp is used.<br/>- **weight**: font weight. For the number type, the value ranges from 100 to 900, at an interval of 100. The default value is **400**. A larger value indicates a larger font weight.<br/>- **family**: font family. Use commas (,) to separate multiple fonts, for example, **'Arial, sans-serif'**. The priority of the fonts is the sequence in which they are placed.<br/>- **style**: font style. |
| enterKeyType | EnterKeyType | EnterKeyType.Done | How the Enter key is labeled. |
| caretColor | Color | - | Color of the caret (also known as the text insertion cursor). |
| maxLength | number | - | Maximum number of characters in the text input. |
| inputFilter<sup>8+</sup> | {<br/>value: [ResourceStr](../../ui/ts-types.md)<sup>8+</sup>,<br/>error?: (value: string)<br/>} | - | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are ignored. The specified regular expression can match single characters, but not strings. Example: ^(? =.\*\d)(? =.\*[a-z])(? =.\*[A-Z]).{8,10}$. Strong passwords containing 8 to 10 characters cannot be filtered.<br>- **value**: regular expression to set.<br>- **error**: error message containing the ignored content returned when regular expression matching fails. |
| copyOption<sup>9+</sup> | [CopyOptions](ts-basic-components-text.md) | CopyOptions.CrossDevice | Whether copy and paste is allowed. |
| showPasswordIcon<sup>9+</sup> | boolean | true | Whether to display the show password icon at the end of the password text box.|
| style<sup>9+</sup> | TextInputStyle | Default | Text input style.|

- EnterKeyType enums
  | Name | Description |
  | -------- | -------- |
  | EnterKeyType.Go | The Enter key is labeled **Go**. |
  | EnterKeyType.Search | The Enter key is labeled **Search**. |
  | EnterKeyType.Send | The Enter key is labeled **Send**. |
  | EnterKeyType.Next | The Enter key is labeled **Next**. |
  | EnterKeyType.Done | The Enter key is labeled **Done**. |

- InputType enums
  | Name | Description |
  | -------- | -------- |
  | InputType.Normal | Normal input mode. |
  | InputType.Password | Password input mode. |
  | InputType.Email | Email address input mode. |
  | InputType.Number | Digit input mode. |

- TextInputStyle
  | Name                | Description           |
  | ------------------ | ------------- |
  | Default   | Default style. The caret width is fixed at 1.5 vp, and the caret height increases with the font size. |
  | Inline | Inline input style. When text is selected, its background height is the same as the height of the text box.     |

## Events

| Name | Description |
| -------- | -------- |
| onChange(value: string) =&gt; void | Triggered when the input changes. |
| onSubmit(callback: (enterKey: EnterKeyType) =&gt; void) | Triggered when the Enter key on the physical or soft keyboard is pressed. |
| onEditChanged(callback:&nbsp;(isEditing:&nbsp;boolean)&nbsp;=&gt;&nbsp;void)<sup>(deprecated) </sup> | Triggered when the input status changes. |
| onEditChange(callback:&nbsp;(isEditing:&nbsp;boolean)&nbsp;=&gt;&nbsp;void) <sup>8+</sup> | Triggered when the input status changes. |
| onCopy<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the copy button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>**value**: text to be copied. |
| onCut<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the cut button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>**value**: text to be cut. |
| onPaste<sup>8+</sup>(callback:(value: string) =&gt; void) | Triggered when the paste button on the pasteboard, which displays when the text box is long pressed, is clicked.<br>**value**: text to be pasted. |

### TextInputController<sup>8+</sup>

Implements the controller of the **\<TextInput>** component.


#### Objects to Import


```
controller: TextInputController = new TextInputController()
```


#### caretPosition

caretPosition(value: number): void

Sets the position of the caret.

- Parameters
  | Name | Type | Mandatory | Default Value | Description |
  | -------- | -------- | -------- | -------- | -------- |
  | value | number | Yes | - | Length from the start of the text string to the position where the caret is located. |



## Example


### Single-line Text Input

```ts
// xxx.ets
@Entry
@Component
struct TextInputExample1 {
  @State text: string = ''

  build() {
    Column() {
      TextInput({ placeholder: 'input your word' })
        .placeholderColor("rgb(0,0,225)")
        .placeholderFont({ size: 30, weight: 100, family: 'cursive', style: FontStyle.Italic })
        .caretColor(Color.Blue)
        .height(50)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
        .fontFamily("sans-serif")
        .fontStyle(FontStyle.Normal)
        .fontColor(Color.Red)
        .onChange((value: string) => {
          this.text = value
        })
      Text(this.text).width('90%')
    }
  }
}
```


![en-us_image_0000001212378402](figures/en-us_image_0000001212378402.gif)


### Setting the Caret

```ts
// xxx.ets
@Entry
@Component
struct TextInputExample2 {
    @State text: string = ''
    controller: TextInputController = new TextInputController()
    build() {
        Column() {
            TextInput({ placeholder: 'Please input your words.', controller:this.controller})
            Button('caretPosition')
                .onClick(() => {
                this.controller.caretPosition(4)
            })
        }
    }
}
```

![en-us_image_0000001212058468](figures/en-us_image_0000001212058468.png)