1# Text Input (TextInput/TextArea)
2
3
4The **TextInput** and **TextArea** components are input components typically used to accept input from the user, such as comments, chat messages, and table content. They can be used in combination with other components to meet more diversified purposes, for example, login and registration. For details, see [TextInput](../reference/apis-arkui/arkui-ts/ts-basic-components-textinput.md) and [TextArea](../reference/apis-arkui/arkui-ts/ts-basic-components-textarea.md).
5
6
7## Creating a Text Box
8
9The **TextInput** component provides single-line text input, while the **TextArea** component provides multi-line text input. To create these components, use the following APIs:
10
11```ts
12TextInput(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextInputController})
13```
14
15```ts
16TextArea(value?:{placeholder?: ResourceStr, text?: ResourceStr, controller?: TextAreaController})
17```
18
19- Single-line text box
20
21  ```ts
22  TextInput()
23  ```
24
25  ![en-us_image_0000001511580844](figures/en-us_image_0000001511580844.png)
26
27
28- Multi-line text box
29
30  ```ts
31  TextArea()
32  ```
33
34  ![en-us_image_0000001562940481](figures/en-us_image_0000001562940481.png)
35
36  The **TextArea** component automatically wraps text so that each line does not have more than the width of the component.
37
38
39  ```ts
40  TextArea({text:"I am TextArea I am TextArea I am TextArea"}).width(300)
41  ```
42
43  ![en-us_image_0000001511580836](figures/en-us_image_0000001511580836.png)
44
45
46## Setting the Input Box Type
47
48The **TextInput** component comes in nine types. You can specify its type by setting the **type** parameter to any of the following: **Normal**, **Password**, **Email**, **Number**, **PhoneNumber**, **USER_NAME**, **NEW_PASSWORD**, **NUMBER_PASSWORD**,<!--Del--> **SCREEN_LOCK_PASSWORD**,<!--DelEnd--> and **NUMBER_DECIMAL**.
49
50
51- Normal type (default type)
52
53  ```ts
54  TextInput()
55    .type(InputType.Normal)
56  ```
57
58  ![en-us_image_0000001562820765](figures/en-us_image_0000001562820765.png)
59
60- Password type
61
62  ```ts
63  TextInput()
64    .type(InputType.Password)
65  ```
66
67  ![en-us_image_0000001511580840](figures/en-us_image_0000001511580840.png)
68
69
70## Setting Styles
71
72- Set the placeholder text displayed when there is no input.
73
74
75  ```ts
76  TextInput({placeholder:'I am placeholder text'})
77  ```
78
79  ![en-us_image_0000001511900400](figures/en-us_image_0000001511900400.png)
80
81
82- Set the current text input.
83
84  ```ts
85  TextInput({placeholder:'I am placeholder text',text:'I am current text input'})
86  ```
87
88  ![en-us_image_0000001562820761](figures/en-us_image_0000001562820761.png)
89
90- Use **backgroundColor** to set the background color of the text box.
91
92  ```ts
93  TextInput({placeholder:'I am placeholder text',text:'I am current text input'})
94    .backgroundColor(Color.Pink)
95  ```
96
97  ![en-us_image_0000001511740444](figures/en-us_image_0000001511740444.png)
98
99  More styles can be implemented by leveraging the [universal attributes](../reference/apis-arkui/arkui-ts/ts-universal-attributes-size.md).
100
101
102## Adding Events
103
104You can add the **onChange** event for the text box to obtain its content changes. You can also add the universal events to implement user interactions.
105
106```ts
107TextInput()
108  .onChange((value: string) => {
109    console.info(value);
110  })
111  .onFocus(() => {
112    console.info('Get Focus');
113  })
114```
115
116## Example Scenario
117
118In this example, the text box is used to submit forms on the user login or registration page.
119
120```ts
121@Entry
122@Component
123struct TextInputSample {
124  build() {
125    Column() {
126      TextInput({ placeholder: 'input your username' }).margin({ top: 20 })
127        .onSubmit((EnterKeyType)=>{
128          console.info(EnterKeyType+'Enter key type')
129        })
130      TextInput({ placeholder: 'input your password' }).type(InputType.Password).margin({ top: 20 })
131        .onSubmit((EnterKeyType)=>{
132          console.info(EnterKeyType+'Enter key type')
133        })
134      Button('Sign in').width(150).margin({ top: 20 })
135    }.padding(20)
136  }
137}
138```
139
140![textinput](figures/textinput.gif)
141
142## Keyboard Avoidance
143
144After the keyboard is raised, scrollable container components will only activate the keyboard avoidance feature when switching between landscape and portrait modes. To enable keyboard avoidance for non-scrollable container components, nest them within a scrollable container component, such as [Scroll](../reference/apis-arkui/arkui-ts/ts-container-scroll.md), [List](../reference/apis-arkui/arkui-ts/ts-container-list.md), or [Grid](../reference/apis-arkui/arkui-ts/ts-container-grid.md).
145
146```ts
147// xxx.ets
148@Entry
149@Component
150struct Index {
151  placeHolderArr: string[] = ['1', '2', '3', '4', '5', '6', '7']
152
153  build() {
154    Scroll() {
155      Column() {
156        ForEach(this.placeHolderArr, (placeholder: string) => {
157          TextInput({ placeholder: 'TextInput ' + placeholder })
158            .margin(30)
159        })
160      }
161    }
162    .height('100%')
163    .width('100%')
164  }
165}
166```
167
168![textinputkeyboardavoid](figures/TextInputKeyboardAvoid.gif)
169
170## Caret Avoidance
171
172The **OFFSET** and **RESIZE** modes of [keyBoardAvoidMode](../../application-dev/reference/apis-arkui/arkui-ts/ts-types.md#keyboardavoidmode11) do not allow for secondary avoidance actions after the keyboard has been lifted. To support additional caret avoidance actions, you can use the **OFFSET_WITH_CARET** and **RESIZE_CARET** options.<br>
173**RESIZE_WITH_CARET** is recommended for scrollable containers, and **OFFSET_WITH_CARET** is recommended for non-scrollable containers.
174
175```ts
176// EntryAbility.ets
177import { KeyboardAvoidMode } from '@kit.ArkUI';
178
179onWindowStageCreate(windowStage: window.WindowStage) {
180  // The main window is created. Set a main page for this ability.
181  hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
182
183  windowStage.loadContent('pages/Index', (err, data) => {
184    let keyboardAvoidMode = windowStage.getMainWindowSync().getUIContext().getKeyboardAvoidMode();
185  windowStage.getMainWindowSync().getUIContext().setKeyboardAvoidMode(KeyboardAvoidMode.OFFSET_WITH_CARET);
186    if (err.code) {
187      hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
188      return;
189    }
190    hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
191  });
192}
193```
194
195```ts
196// xxx.ets
197@Entry
198@Component
199struct Index {
200  @State caretPosition: number = 600
201  areaController: TextAreaController = new TextAreaController()
202
203  text = "Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
204  So the best way to destroy happiness is to look at something and focus on even the smallest flaw. It is the smallest flaw that would make us complain. And it is the complaint that leads to us becoming unhappy.\
205  If one chooses to be happy, he will be blessed; if he chooses to be unhappy, he will be cursed. Happiness is just what you think will make you happy.Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
206  So the best way to destroy happiness is to look at something and focus on even the smallest flaw. It is the smallest flaw that would make us complain. And it is the complaint that leads to us becoming unhappy.\
207  If one chooses to be happy, he will be blessed; if he chooses to be unhappy, he will be cursed. Happiness is just what you think will make you happy.Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
208  So the best way to destroy happiness is to look at something and focus on even the smallest flaw. It is the smallest flaw that would make us complain. And it is the complaint that leads to us becoming unhappy.\
209  If one chooses to be happy, he will be blessed; if he chooses to be unhappy, he will be cursed. Happiness is just what you think will make you happy.Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
210  So the best way to destroy happiness is to look at something and focus on even the smallest flaw. It is the smallest flaw that would make us complain. And it is the complaint that leads to us becoming unhappy.\
211  If one chooses to be happy, he will be blessed; if he chooses to be unhappy, he will be cursed. Happiness is just what you think will make you happy.Most of us compare ourselves with anyone we think is happier — a relative, someone we know a lot, or someone we hardly know. As a result, what we do remember is anything that makes others happy, anything that makes ourselves unhappy, totally forgetting that there is something happy in our own life.\
212  ";
213
214  build() {
215    Scroll() {
216      Column() {
217        Row() {
218          Button('CaretPostiion++: ' + this.caretPosition).onClick(() => {
219            this.caretPosition += 1
220          }).fontSize(10)
221          Button('CaretPostiion--: ' + this.caretPosition).onClick(() => {
222            this.caretPosition -= 1
223          }).fontSize(10)
224          Button('SetCaretPostion:').onClick(() => {
225            this.areaController.caretPosition(this.caretPosition)
226          }).fontSize(10)
227        }
228
229        TextArea({ text: this.text, controller: this.areaController })
230          .width('100%')
231          .fontSize('20fp')
232      }
233    }.width('100%').height('100%')
234  }
235}
236```
237
238![textinputkeyboardavoid](figures/caretavoid.gif)
239
240