Search

17:06

Description

An input with a search icon, a clear control and an optional action button, two-way bound via v-model. Pressing enter (confirm-type="search") emits search, tapping the action button emits custom, input changes emit input / change, and the clear control appears when the field is focused and non-empty.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported (the animation expand has no transition — the action button shows/hides instantly)

Examples

Basic Usage

Supports v-model binding, monitors events via @change, @search, @custom, @clear.

View source

<template>
    <ux-search v-model="value" @search="onSearch" />
</template>

<script setup lang="uts">
const value = ref<string>('');

const onSearch = (val: string) => {
    uni.showToast({ title: '搜索: ' + val, icon: 'none' });
};
</script>

Shape

shape="square" is a small radius (4px, default), shape="round" is a capsule.

View source

<template>
    <!-- 两档形状全演示：square 小圆角（4px，不传即此档） / round 胶囊 -->
    <ux-search v-model="squareValue" shape="square" />
    <ux-search v-model="roundValue" shape="round" />
</template>

<script setup lang="uts">
const squareValue = ref<string>('');
const roundValue = ref<string>('');
</script>

Clearable

clearabled controls the clear icon visibility, shown when focused and has content.

View source

<template>
    <ux-search v-model="value" :clearabled="true" />
</template>

<script setup lang="uts">
const value = ref<string>('可清除内容');
</script>

Action Button

show-action controls the right search button, click triggers @custom event.

View source

<template>
    <ux-search v-model="value" :show-action="true" @custom="onCustom" />
</template>

<script setup lang="uts">
const value = ref<string>('');

const onCustom = (val: string) => {
    uni.showToast({ title: '点击了右侧按钮: ' + val, icon: 'none' });
};
</script>

Animation

When animation is true, the action button expands on focus and collapses on blur.

View source

<template>
    <ux-search v-model="value" :animation="true" />
</template>

<script setup lang="uts">
const value = ref<string>('');
</script>

Input Align

input-align controls the horizontal alignment of input text.

View source

<template>
    <ux-search v-model="value" input-align="center" />
</template>

<script setup lang="uts">
const value = ref<string>('');
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
shape	Search box shape (see SearchShape in types/global.uts): square – small radius 4px (default), round – capsule	SearchShape	'square'	-
bgColor	Search box background color	string	''	-
borderColor	Border color; a border appears only when a color is set	string	''	-
placeholder	Placeholder text	string	''	-
clearabled	Whether to enable the clear control	boolean	true	-
focus	Whether to focus automatically	boolean	false	-
showAction	Whether to show the right-side action button	boolean	true	-
actionText	Text of the right-side action button	string	''	-
actionStyle	Style of the right-side action button, as an object	UTSJSONObject	-	-
inputAlign	Horizontal alignment of the input text	InputAlign	'left'	-
inputStyle	Custom input style, as an object	UTSJSONObject	-	-
disabled	Whether the input is disabled	boolean	false	-
animation	Whether to enable the animation (see the description above)	boolean	false	-
searchIconColor	Search icon color; defaults to the input text color	string	''	-
color	Input text color	string	''	-
placeholderColor	Placeholder color	string	''	-
searchIcon	Search icon: a uView icon name or an image path	string	'search'	-
margin	Distance from surrounding elements; a string with units, e.g. "15px"	string	'0'	-
height	Input height in px	string | number	32	-
maxlength	Maximum input length; -1 means unlimited	string | number	-1	-
modelValue	Initial input content	string	''	-
adjustPosition	Whether to adjust the height automatically when the keyboard pops up	boolean	true	-

Events

Event	Description	Params	Version
input	Fires when the input content changes	value: string	-
change	Fires when the input content changes	value: string	-
search	Fires when the user confirms the search	value: string	-
custom	Fires when the user taps the right-side action button	value: string	-
clear	Fires when the user taps the clear button	-	-
focus	Fires when the input gains focus	value: string	-
blur	Fires when the input loses focus	value: string	-
click	Fires when the search box is tapped (only when disabled=true)	-	-

Slots

ux-search has no slots.

Notes

• animation only takes effect together with show-action (expands on focus, collapses on blur); on WeChat Mini Program there is no transition, so the action button shows/hides instantly.
• When disabled is true the input cannot be edited, and only then does tapping the whole component emit click (it is not emitted otherwise).
• Tapping the clear icon also fires the input's @blur; the component delays clearing the focused state by 100ms so the icon stays tappable, and clear is emitted 50ms later.
• When placeholder / action-text are not passed, the component falls back to its built-in locale text.
• On App, input-align is also written into the inline placeholder-style, so the placeholder and the typed text share the same alignment.