Input 输入框

邮箱

我们绝不会共享你的邮箱

import { Input } from "@lark-ui/core";

export function InputBasicDemo() {
  return (
    <Input
      label="邮箱"
      placeholder="you@example.com"
      description="我们绝不会共享你的邮箱"
    />
  );
}

安装

统一导出

import { Input } from "@lark-ui/core";

按需导出

import { Input } from "@lark-ui/core/components/input";

用法

使用内置 Field（推荐）

使用 label 属性可启用内置的 Field 包装器，获得标签、描述和错误提示支持。

import { Input } from "@lark-ui/core";

export default function Example() {
  return (
    <Input
      label="Email"
      placeholder="you@example.com"
      description="We'll never share your email"
    />
  );
}

裸用 Input（自定义布局）

在自定义表单布局中，请不要使用 label，直接使用 Input。出于无障碍考虑，必须提供 aria-label 或 aria-labelledby。

import { Input } from "@lark-ui/core";

export default function Example() {
  return <Input placeholder="Search..." aria-label="Search products" />;
}

示例

带标签和描述

label 属性可启用内置的 Field 包装器，并自动采用纵向布局（标签位于输入框上方）。

用户名

3-20 个字符，仅支持字母和数字

import { Input } from "@lark-ui/core";

export function InputWithLabelDemo() {
  return (
    <Input
      label="用户名"
      placeholder="选择一个用户名"
      description="3-20 个字符，仅支持字母和数字"
    />
  );
}

带错误（字符串）

简单的错误信息可以直接将 error 作为字符串传入。当 error 属性为真值时，会自动应用错误样式。

邮箱

请输入有效的邮箱地址

import { Input } from "@lark-ui/core";

export function InputErrorStringDemo() {
  return (
    <Input
      label="邮箱"
      placeholder="you@example.com"
      value="invalid-email"
      error="请输入有效的邮箱地址"
    />
  );
}

带错误（校验对象）

HTML5 校验可将 error 作为包含 message 和 match 的对象传入。当字段有效性匹配时显示错误。

密码

import { Input } from "@lark-ui/core";

export function InputErrorObjectDemo() {
  return (
    <Input
      label="密码"
      type="password"
      value="short"
      error={{
        message: "密码至少需要 8 个字符",
        match: "tooShort",
      }}
      minLength={8}
    />
  );
}

输入框尺寸

提供四种尺寸：xs、sm、base（默认）、lg。

极小

小

基础

大

import { Input } from "@lark-ui/core";

export function InputSizesDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Input size="xs" label="极小" placeholder="极小尺寸输入框" />
      <Input size="sm" label="小" placeholder="小尺寸输入框" />
      <Input label="基础" placeholder="基础尺寸输入框（默认）" />
      <Input size="lg" label="大" placeholder="大尺寸输入框" />
    </div>
  );
}

禁用

禁用字段

import { Input } from "@lark-ui/core";

export function InputDisabledDemo() {
  return <Input label="禁用字段" placeholder="无法编辑" disabled />;
}

可选字段

设置 required={false} 可在标签后显示”(optional)“文本。

电话号码(optional)

import { Input } from "@lark-ui/core";

export function InputOptionalFieldDemo() {
  return (
    <Input label="电话号码" required={false} placeholder="+1 (555) 000-0000" />
  );
}

带标签工具提示

使用 labelTooltip 可添加一个信息图标，悬停时显示补充说明。

API 密钥

import { Input } from "@lark-ui/core";

export function InputLabelTooltipDemo() {
  return (
    <Input
      label="API 密钥"
      labelTooltip="可在控制台的 设置 > API 密钥 中找到"
      placeholder="sk_live_..."
    />
  );
}

ReactNode 标签

label 属性接受 ReactNode，便于富文本格式化。

用于账单的邮箱

import { Input } from "@lark-ui/core";

export function InputReactNodeLabelDemo() {
  return (
    <Input
      label={
        <span>
          用于<strong>账单</strong>的邮箱
        </span>
      }
      required
      placeholder="billing@company.com"
      type="email"
    />
  );
}

使用 onChange 的受控用法

标准的 React onChange 处理器会接收到完整的事件对象。使用 e.target.value 获取值。

使用 onChange

使用 e.target.value

import { useState } from "react";
import { Input } from "@lark-ui/core";

/** 使用 `onChange`（原生 React 事件）的受控输入框。 */
export function InputControlledOnChangeDemo() {
  const [value, setValue] = useState("");
  return (
    <Input
      label="使用 onChange"
      placeholder="输入一些内容…"
      description={value ? `值：${value}` : "使用 e.target.value"}
      value={value}
      onChange={(e) => setValue(e.target.value)}
    />
  );
}

使用 onValueChange 的受控用法

onValueChange 是 Base UI 提供的便捷处理器，直接给出字符串值——无需解包事件。它与 Select、Combobox 和 Radio.Group 使用的是同一套模式。

使用 onValueChange

直接接收值

import { useState } from "react";
import { Input } from "@lark-ui/core";

/** 使用 `onValueChange` 的受控输入框（Base UI 的便捷写法——直接提供字符串）。 */
export function InputControlledOnValueChangeDemo() {
  const [value, setValue] = useState("");
  return (
    <Input
      label="使用 onValueChange"
      placeholder="输入一些内容…"
      description={value ? `值：${value}` : "直接接收值"}
      value={value}
      onValueChange={(v) => setValue(v)}
    />
  );
}

裸用 Input（无标签）

不带 label 的 Input 会渲染为裸输入框。出于无障碍考虑，必须提供 aria-label。

import { Input } from "@lark-ui/core";

export function InputBareDemo() {
  return <Input placeholder="搜索…" aria-label="搜索产品" />;
}

无标签时的错误提示

即使没有可见的 label，错误信息和描述也会正常渲染——请使用 aria-label 保证输入框的无障碍体验。

请输入有效的主机名

路径必须以 / 开头

import { Input } from "@lark-ui/core";

/** 没有可见标签的输入框（Input），通过 `aria-label` 传达错误和描述信息。 */
export function InputErrorWithoutLabelDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Input
        aria-label="主机名"
        placeholder="example.com"
        value="not a host"
        error="请输入有效的主机名"
      />
      <Input
        aria-label="路径"
        placeholder="/api/v1/users"
        value="missing-slash"
        error={{ message: "路径必须以 / 开头", match: true }}
      />
    </div>
  );
}

输入类型

支持所有 HTML input 类型：text、email、password、number、tel、url 等。

邮箱

密码

年龄

电话

import { Input } from "@lark-ui/core";

export function InputTypesDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Input type="email" label="邮箱" placeholder="you@example.com" />
      <Input type="password" label="密码" placeholder="••••••••" />
      <Input type="number" label="年龄" placeholder="18" />
      <Input type="tel" label="电话" placeholder="+1 (555) 000-0000" />
    </div>
  );
}

密码管理器浮层

对于密码管理器可能误判为登录字段的非凭据输入框，请设置 passwordManagerIgnore。

API 密钥（默认）

API 密钥（passwordManagerIgnore）

import { Input } from "@lark-ui/core";

/** 并排对比：Keeper 在默认输入框上显示图标，在忽略密码管理的输入框上则不显示。 */
export function InputPasswordManagerIgnoreDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Input
        label="API 密钥（默认）"
        type="password"
        placeholder="sk_live_..."
      />
      <Input
        label="API 密钥（passwordManagerIgnore）"
        type="password"
        placeholder="sk_live_..."
        passwordManagerIgnore
      />
    </div>
  );
}

API 参考

Input 接受所有标准 HTML input 属性，以及以下属性：

属性	类型	默认值	说明
label	`ReactNode`	-	输入框的标签内容（启用 Field 包裹层）——可以是字符串或任意 React 节点
labelTooltip	`ReactNode`	-	通过信息图标显示在标签旁的工具提示内容
description	`ReactNode`	-	显示在输入框下方的辅助说明文字
error	`string \| object`	-	错误信息或校验错误对象
passwordManagerIgnore	`boolean`	-	在非凭据类输入框上屏蔽浏览器扩展密码管理器的浮层。
size	`"xs" \| "sm" \| "base" \| "lg"`	`"base"`	输入框尺寸。 - `"xs"` — 适合紧凑界面的超小尺寸 - `"sm"` — 适合次要字段的小尺寸 - `"base"` — 默认尺寸 - `"lg"` — 适合突出字段的大尺寸
variant	`"default" \| "error"`	`"default"`	视觉变体。 - `"default"` — 标准输入框 - `"error"` — 校验失败时的错误状态

校验错误类型

将 error 用作对象时，match 属性对应 HTML5 ValidityState 的取值：

匹配值	说明
valueMissing	必填字段为空
typeMismatch	值与类型不匹配（例如邮箱格式无效）
patternMismatch	值与 pattern 属性不匹配
tooShort	值短于 minLength
tooLong	值长于 maxLength
rangeUnderflow	值小于 min
rangeOverflow	值大于 max
true	始终显示错误（用于服务端校验）

无障碍

标签要求

输入框需要通过以下方式之一获得无障碍名称：

label 属性（推荐）
裸输入框使用 placeholder + aria-label
自定义标签关联使用 aria-labelledby

缺少无障碍名称会在开发模式下触发控制台警告。

错误关联

错误信息会通过 ARIA 属性自动与输入框关联，以便屏幕阅读器播报。

Lark