# Search The **\** component provides an area for users to enter search queries. > **NOTE** > > This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. ## Child Components Not supported ## APIs Search(options?: { value?: string; placeholder?: ResourceStr; icon?: string; controller?: SearchController }) **Parameters** | Name | Type | Mandatory| Description | | ----------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | | value | string | No | Text input in the search text box.
Since API version 10, this parameter supports two-way binding through [$$](../../quick-start/arkts-two-way-sync.md).| | placeholder | [ResourceStr](ts-types.md#resourcestr)10+ | No | Text displayed when there is no input. | | icon | string | No | Path to the search icon. By default, the system search icon is used.
**NOTE**
The icon data source can be a local or online image.
- The supported formats include PNG, JPG, BMP, SVG, GIF, and pixelmap.
- The Base64 string is supported in the following format: data:image/[png\|jpeg\|bmp\|webp];base64,[base64 data], where [base64 data] is a Base64 string.| | controller | SearchController | No | Controller of the **\** component. | ## Attributes In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. | Name | Type | Description | | ----------------------- | ------------------------------------------------ | ---------------------------------------------- | | searchButton10+ | value: string,
option?: [SearchButtonOptions](#searchbuttonoptions10) | Text on the search button located next to the search text box. By default, there is no search button. | | placeholderColor | [ResourceColor](ts-types.md#resourcecolor) | Placeholder text color.
Default value: **'#99182431'** | | placeholderFont | [Font](ts-types.md#font) | Placeholder text style, including the font size, font width, font family, and font style. Currently, only the default font family is supported. | | textFont | [Font](ts-types.md#font) | Style of the text entered in the search box, including the font size, font width, font family, and font style. Currently, only the default font family is supported. | | textAlign | [TextAlign](ts-appendix-enums.md#textalign) | Text alignment mode in the search text box.
Default value: **TextAlign.Start** | | copyOption9+ | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether copy and paste is allowed.
Default value: **CopyOptions.LocalDevice**
If this attribute is set to **CopyOptions.None**, the text can be pasted, but copy or cut is not allowed. | | searchIcon10+ | [IconOptions](#iconoptions10) | Style of the search icon on the left. | | cancelButton10+ | {
style? : [CancelButtonStyle](#cancelbuttonstyle10)
icon?: [IconOptions](#iconoptions10)
} | Style of the Cancel button on the right.
Default value:
{
style: CancelButtonStyle.INPUT
} | | fontColor10+ | [ResourceColor](ts-types.md#resourcecolor) | Font color of the input text.
Default value: **'#FF182431'**
**NOTE**
[Universal text attributes](ts-universal-attributes-text-style.md) **fontSize**, **fontStyle**, **fontWeight**, and **fontFamily** are set in the **textFont** attribute.| | caretStyle10+ | [CaretStyle](#caretstyle10) | Caret style.
Default value:
{
width: 1.5vp
color: '#007DFF'
} | | enableKeyboardOnFocus10+ | boolean | Whether to enable the input method when the component obtains focus.
Default value: **true** | | selectionMenuHidden10+ | boolean | Whether to display the text selection menu when the text box is long-pressed or right-clicked.
Default value: **false**| ## IconOptions10+ | Name| Type | Mandatory| Description | | ------ | ------------------------------------------ | ---- | ----------- | | size | [Length](ts-types.md#length) | No | Icon size. | | color | [ResourceColor](ts-types.md#resourcecolor) | No | Icon color. | | src | [ResourceStr](ts-types.md#resourcestr) | No | Image source of the icon.| ## CaretStyle10+ | Name| Type | Mandatory| Description| | ------ | ------------------------------------------ | ---- | -------- | | width | [Length](ts-types.md#length) | No | Caret width.| | color | [ResourceColor](ts-types.md#resourcecolor) | No | Caret color.| ## SearchButtonOptions10+ | Name | Type | Mandatory| Description | | --------- | ------------------------------------------ | ---- | ---------------- | | fontSize | [Length](ts-types.md#length) | No | Font size of the button.| | fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the button.| ## CancelButtonStyle10+ | Name | Description | | ----------------------- | ---------------- | | CONSTANT | The Cancel button is always displayed.| | INVISIBLE | The Cancel button is always hidden.| | INPUT | The Cancel button is displayed when there is text input.| ## Events In addition to the [universal events](ts-universal-events-click.md), the following events are supported. | Name | Description | | ------------------------------------------------------------ | ------------------------------------------------------------ | | onSubmit(callback: (value: string) => void) | Triggered when users click the search icon or the search button, or touch the search button on a soft keyboard.
- **value**: current text input.| | onChange(callback: (value: string) => void) | Triggered when the input in the text box changes.
- **value**: current text input.| | onCopy(callback: (value: string) => void) | Triggered when data is copied to the pasteboard, which is displayed when the search text box is long pressed.
- **value**: text copied.| | onCut(callback: (value: string) => void) | Triggered when data is cut from the pasteboard, which is displayed when the search text box is long pressed.
- **value**: text cut.| | onPaste(callback: (value: string) => void) | Triggered when data is pasted from the pasteboard, which is displayed when the search text box is long pressed.
-**value**: text pasted.| | onTextSelectionChange(callback: (selectionStart: number, selectionEnd: number) => void)10+ | Triggered when the text selection position changes.
**selectionStart**: start position of the text selection area. The start position of text in the text box is **0**.
**selectionEnd**: end position of the text selection area.| | onContentScroll(callback: (totalOffsetX: number, totalOffsetY: number) => void)10+ | Triggered when the text content is scrolled.
**totalOffsetX**: X coordinate offset of the text in the content area.
**totalOffsetY**: Y coordinate offset of the text in the content area.| ## SearchController Implements the controller of the **\** component. Currently, the controller can be used to control the caret position. ### Objects to Import ``` controller: SearchController = new SearchController() ``` ### caretPosition caretPosition(value: number): void Sets the position of the caret. **Parameters** | Name| Type| Mandatory| Description | | ------ | -------- | ---- | ---------------------------------- | | value | number | Yes | Length from the start of the character string to the position where the caret is located.| ### stopEditing10+ stopEditing(): void Exits the editing state. ### getTextContentRect10+ getTextContentRect(): [RectResult](#rectresult10) Obtains the position of the edited text area relative to the component and its size. The unit of the return value is pixel. **Return value** | Type | Description | | ------------------- | -------- | | [RectResult](#rectresult10) | Position of the edited text area relative to the component and its size.| > **NOTE** > > - The returned position information is the offset of the first character relative to the search icon in the **\** component. > - If no text is entered, the return value contains the position information, but the size is 0. ### RectResult10+ Describes the position and size. | Parameter | Type | Description| | ------- | ------ | ----------------------- | | x | number | X coordinate.| | y | number | Y coordinate.| | width | number | Content width.| | height | number | Content height.| ### getTextContentLineCount10+ getTextContentLineCount(): number Obtains the number of lines of the edited text. **Return value** | Type | Description | | ----- | -------- | | number| Number of lines of the edited text.| ## Example ### Example 1 ```ts // xxx.ets @Entry @Component struct SearchExample { @State changeValue: string = '' @State submitValue: string = '' controller: SearchController = new SearchController() build() { Column() { Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) Text('onChange:' + this.changeValue).fontSize(18).margin(15) Search({ value: this.changeValue, placeholder: 'Type to search...', controller: this.controller }) .searchButton('SEARCH') .width('95%') .height(40) .backgroundColor('#F5F5F5') .placeholderColor(Color.Grey) .placeholderFont({ size: 14, weight: 400 }) .textFont({ size: 14, weight: 400 }) .onSubmit((value: string) => { this.submitValue = value }) .onChange((value: string) => { this.changeValue = value }) .margin(20) Button('Set caretPosition 1') .onClick(() => { // Move the caret to after the first entered character. this.controller.caretPosition(1) }) }.width('100%') } } ``` ![search](figures/search.gif) ### Example 2 ```ts // xxx.ets @Entry @Component struct SearchButtoonExample { @State submitValue: string = '' build() { Column() { Text('onSubmit:' + this.submitValue).fontSize(18).margin(15) Search({ placeholder: 'Type to search...' }) .searchButton('SEARCH') .searchIcon({ src: $r('app.media.search') }) .cancelButton({ style: CancelButtonStyle.CONSTANT, icon: { src: $r('app.media.cancel') } }) .width('90%') .height(40) .backgroundColor('#F5F5F5') .placeholderColor(Color.Grey) .placeholderFont({ size: 14, weight: 400 }) .textFont({ size: 14, weight: 400 }) .onSubmit((value: string) => { this.submitValue = value }) .margin(20) }.width('100%') } } ``` ![searchButton](figures/searchButton.gif)