---
title: Input 输入框
description: 接受标准 HTML 属性的原生单行文本输入组件
links:
  rac: Input
  source: input/input.tsx
  styles: input.css
  storybook: Components/Forms/Input
---

## 用法

```tsx
import { Input } from '@heroui/react';
```

<ComponentPreview name="input-basic" />

<Callout>
  校验、标签与错误消息请参阅 **[TextField](/docs/components/text-field)**。
</Callout>

## 示例

### 变体

Input 组件支持两种视觉变体：

- **`primary`**（默认）- 标准样式带阴影，适用于大多数场景
- **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内

<ComponentPreview name="input-variants" />

### 表面样式

在 [Surface](/docs/components/surface) 内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。

<ComponentPreview name="input-on-surface" />

### 宽度充满

<ComponentPreview name="input-full-width" />

### 输入类型

<ComponentPreview name="input-types" />

### 受控组件

<ComponentPreview name="input-controlled" />

## 自定义样式

### Tailwind CSS

<ComponentPreview name="input-custom-styles" />

### 全局 CSS

基础类 `.input` 驱动每个实例。使用 `@layer components` 一次性覆盖。

```css
@layer components {
  .input {
    @apply rounded-lg border border-border bg-surface px-4 py-2 text-sm shadow-sm transition-colors;

    &:hover,
    &[data-hovered="true"] {
      @apply bg-surface-secondary border-border/80;
    }

    &:focus-visible,
    &[data-focus-visible="true"] {
      @apply border-accent ring-2 ring-accent/20;
    }

    &[data-invalid="true"] {
      @apply border-danger bg-danger-soft text-danger;
    }
  }
}
```

## 样式参考

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

#### 基础类 [!toc]

- `.input` – 原生 input 元素样式

### 交互状态

- **Hover**：`:hover` 或 `[data-hovered="true"]`
- **Focus Visible**：`:focus-visible` 或 `[data-focus-visible="true"]`
- **Invalid**：`[data-invalid="true"]`（与 `aria-invalid` 同步）
- **Disabled**：`:disabled` 或 `[aria-disabled="true"]`
- **Read Only**：`[aria-readonly="true"]`

## API 参考

### Input

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

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 与组件样式合并的 Tailwind 类 |
| `type` | `string` | `"text"` | 输入类型（text、email、password、number 等） |
| `value` | `string` | - | 受控值 |
| `defaultValue` | `string` | - | 非受控初始值 |
| `onChange` | `(event: React.ChangeEvent<HTMLInputElement>) => void` | - | 变化处理函数 |
| `placeholder` | `string` | - | 占位文本 |
| `disabled` | `boolean` | `false` | 是否禁用 |
| `readOnly` | `boolean` | `false` | 是否只读 |
| `required` | `boolean` | `false` | 是否必填 |
| `name` | `string` | - | 表单提交时的 name |
| `autoComplete` | `string` | - | 浏览器自动完成提示 |
| `maxLength` | `number` | - | 最大字符数 |
| `minLength` | `number` | - | 最小字符数 |
| `pattern` | `string` | - | 校验用正则模式 |
| `min` | `number \| string` | - | 最小值（number/date 输入） |
| `max` | `number \| string` | - | 最大值（number/date 输入） |
| `step` | `number \| string` | - | 步进间隔（number 输入） |
| `fullWidth` | `boolean` | `false` | 是否占满容器宽度 |
| `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 |

> 校验 props 如 `isInvalid`、`isRequired` 与错误处理，请使用 **[TextField](/docs/components/text-field)** 并将 Input 作为子组件。

## 相关组件

<RelatedComponents component="input" />