Input

17:06

Description

Input field. type supports text, number, password, digit, textarea, select and more; border accepts surround (all four sides) / bottom (bottom only) / none (no border, the default). Built-in clear, password reveal and character count. Borderless and transparent by default; placed inside ux-form-item it inherits the item's size and triggers form validation on input / blur.

Compatibility

Platform	Support
App	✅ Supported (native input text color / alignment / placeholder are inlined by the component; page class cannot override the input text color)
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Bind the input value with v-model; border shows the outline.

View source

<template>
    <ux-input v-model="value" placeholder="请输入内容" border />
    <text class="input-status">当前输入: {{ value }}</text>
</template>

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

<style scoped>
.input-status {
    font-size: 13px;
    color: #606266;
    margin-top: 8px;
}
</style>

Type (type)

Supports text / number / password / textarea and more.

View source

<template>
    <ux-input v-model="value" :type="type" placeholder="请输入内容" border />
</template>

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

Alignment (input-align)

Set the text alignment of the input via input-align.

View source

<template>
    <ux-input v-model="value" input-align="center" placeholder="居中对齐" border />
</template>

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

Size (size)

Supports small / default / large presets and custom values (px).

View source

<template>
    <ux-input v-model="value" size="large" placeholder="大尺寸输入框" border />
</template>

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

Custom Font Size (font-size)

Set the font size via font-size, which takes precedence over the size preset.

View source

<template>
    <ux-input v-model="value" font-size="20" placeholder="自定义字号" border />
</template>

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

Border Color (border-color)

Customize the border color via border-color; requires border to be enabled.

View source

<template>
    <ux-input v-model="value" placeholder="自定义边框颜色" border border-color="#19be6b" />
</template>

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

Password (password)

type=password shows an eye icon by default; click to toggle plain text.

View source

<template>
    <ux-input v-model="value" type="password" :password-icon="true" placeholder="请输入密码" border />
</template>

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

Clearable (clearable)

When clearable=true, a clear icon appears after typing; click to clear.

View source

<template>
    <ux-input v-model="value" :clearable="true" placeholder="可一键清空" border />
</template>

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

Word Count (count)

When type=textarea and count=true, word count shows at the bottom right.

View source

<template>
    <ux-input v-model="value" type="textarea" :count="true" :maxlength="100" placeholder="支持字数统计" border />
</template>

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

Disabled / Readonly

disabled blocks input; readonly prevents editing but still triggers the click event.

View source

<template>
    <ux-input v-model="disabledValue" disabled placeholder="禁用状态" border />
    <ux-input v-model="readonlyValue" readonly placeholder="只读状态" border />
</template>

<script setup lang="uts">
const disabledValue = ref<string>('禁用状态');
const readonlyValue = ref<string>('只读状态');
</script>

Custom Height (height)

Set the input height via height in px; auto for automatic height.

View source

<template>
    <ux-input v-model="value" :height="50" placeholder="自定义高度" border />
</template>

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

Prefix Content (prefix)

Use the prefix slot to place an icon or custom content before the input area, common for amount, unit fields.

View source

<template>
    <ux-input v-model="value" type="digit" placeholder="请输入金额" border>
        <template #prefix>
            <ux-icon name="rmb-circle-fill" :size="8" />
        </template>
    </ux-input>
</template>

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

Auto Focus (focus)

When focus=true the input gains focus on load; pairs with selection-start/selection-end to select text.

View source

<template>
    <ux-input v-model="value" :focus="focus" placeholder="自动聚焦的输入框" border />
</template>

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

Auto Height (auto-height)

When type=textarea and auto-height=true, the input area grows with content.

View source

<template>
    <ux-input v-model="value" type="textarea" :auto-height="autoHeight" placeholder="多行输入，自动增高" border />
</template>

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

Trim Whitespace (trim)

When trim=true, leading and trailing whitespace is removed from input.

View source

<template>
    <ux-input v-model="value" :trim="trim" placeholder="输入带空格的内容" border />
</template>

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

Validation State (validate-state)

When validate-state=true the border turns red for validation failure feedback.

View source

<template>
    <ux-input v-model="value" :validate-state="validateState" placeholder="验证失败示例" border />
</template>

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

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
modelValue	Value bound to the input via v-model	string | number	''	-
type	Input type: textarea, text, number, etc.	InputType	'text'	-
inputAlign	Text alignment of the input	InputAlign	'left'	-
size	Size of the input text	SizeType | ''	''	-
fontSize	Font size of the input content (falls back to the size preset when unset)	string | number	''	-
placeholder	Placeholder text	string	''	-
disabled	Whether the input is disabled	boolean	false	-
readonly	Whether the input is read-only	boolean	false	-
maxlength	Maximum input length	number | string	140	-
count	Whether to show the character count	boolean	false	-
cursorColor	Cursor color	string	''	-
placeholderStyle	Placeholder style	string	''	-
confirmType	Text of the keyboard's bottom-right button	InputConfirmType	'done'	-
fixed	Whether the textarea is inside a fixed-position area	boolean	false	-
focus	Whether to auto-focus	boolean	false	-
passwordIcon	Whether to show the right-hand password icon for the password type	boolean	true	-
border	Border style	boolean | BorderType	'none'	-
borderColor	Border color of the input	string	''	-
autoHeight	Whether the input area grows automatically	boolean	true	-
selectOpen	For type=select, rotates the right icon to indicate open/closed state	boolean	false	-
height	Height in px	number | string	''	-
clearable	Whether the input can be cleared	boolean	true	-
cursorSpacing	Distance between the cursor and the keyboard, in px	number | string	0	-
selectionStart	Cursor start position	number | string	-1	-
selectionEnd	Cursor end position	number | string	-1	-
trim	Whether to trim whitespace at both ends automatically	boolean	true	-
showConfirmbar	Whether to show the bar with the "Done" button above the keyboard	boolean	true	-
adjustPosition	Whether to adjust the height automatically when the keyboard pops up	boolean	true	-
confirmHold	Whether to keep the keyboard open when the bottom-right button is tapped	boolean	false	-
validateState	Validation state of the input	boolean	false	-

Events

Event	Description	Params	Version
input	Fires when the input value changes	value: string	-
change		value: string	-
blur	Fires when the input loses focus	value: string	-
focus	Fires when the input gains focus	value: string	-
confirm	Fires when the keyboard confirm button is tapped	value: string	-
click	Fires when the input is clicked	event: UniEvent	-
clear	Fires when the clear icon is tapped	event: UniEvent	-

Slots

Slot	Description	Version
prefix	Content rendered before the input area (e.g. a currency prefix icon); shown only when provided	-

Notes

1. border defaults to 'none' (no border), the opposite of ux-textarea's 'surround'; border also accepts true/false as convenience aliases for 'surround'/'none'.
2. count is only shown when type="textarea"; maxlength defaults to 140.
3. clearable defaults to true; the clear icon appears when focused with a non-empty value and not disabled, and hides ~100ms after blur to avoid blur firing first and making the icon unclickable.
4. readonly keeps the style unchanged, stays clickable and still emits click; type="select" is likewise forced read-only. The component captures clicks with a transparent overlay (a native input with disabled blocks click bubbling).
5. type="select" forces the input read-only and shows a right-hand dropdown arrow; select-open controls whether the arrow rotates (usually paired with a popup).
6. On App, adjust the input text color / size / alignment via props such as font-size, custom-style and input-align; page class has no effect on native input content.
7. Inside ux-form-item, size is inherited from the form item, validate-state ORs with the form item's validation state, and input / blur trigger the corresponding validation.