---
summary: 1 行または複数行のテキストを自由入力させる入力欄
category: Forms
---

# TextField

ラベルと補足説明を備えた、テキストを自由入力させるための入力欄です。複数行の入力は component="textarea" で切り替えます。
素の `<input type="text">` や `<textarea>` の代わりに使います。
定義済みの選択肢から選ばせる場合は Select を使ってください。

## 基本の使い方

```tsx
import { TextField } from 'wip-ui'

<TextField label="メールアドレス" name="email" type="email" autoComplete="email" placeholder="email@example.com" />
```

## 使う場面

- 名前やメールアドレスなど、短いテキストを入力させるとき
- 説明文や問い合わせ内容など、改行を含む長文を入力させるとき（component="textarea"）

## 使い方

### ラベルと補足説明

- [must] label を付ける。検索など、コンテキストからひと目で分かる場合を除いて省略しない
- [should] 入力形式の例や文字数制限など、入力のルールは caption で示す

### 入力の種類

- [should] 改行を含むテキストの入力には component="textarea" を使う
- [should] メールアドレスや電話番号など、種類が決まっている入力では、それに合ったキーボードが出るようにする
- [should] 名前・住所・メールアドレスなど、利用者自身の情報を入力させる場合は、ブラウザの自動入力が使えるようにする

### 初期値

- [should] 既存の値がある場合は、その値を初期値にする。ない場合は空にする

### 状態

- [should] エラーは、何をどう直せばよいかが分かる文言で示す
- [should] 入力が必須の項目には isRequired を指定する
- [should] 権限不足や条件未達で編集できない場合は isDisabled を指定する
- [should] 編集はさせないが、値を表示して送信内容に含める場合は isReadOnly を使い、caption で読み取り専用であることを伝える

### サイズと幅

- [should] テーブル内やフィルターなど、スペースが限られる場面では size="s" を使う
- [should] size="l" の入力要素やボタンと並べる場合は、size="l" にそろえる
- [should] 幅は、入力される値の長さに合わせる。他の入力要素と幅をそろえたい場合は width を指定する（例：full）
- 入力欄の先頭・末尾にアイコン、テキスト（単位など）、ボタンを入れることには対応していない

## 文言

- [should] label は入力すべき内容を簡潔に示し、モバイル幅でも1行に収まる短さにする
- [should] placeholder には記入例を入れる
- [avoid] placeholder を label の代わりにしない
- [avoid] 入力に欠かせない情報を placeholder だけに書かない。入力を始めると消えるため、caption に書く

## アクセシビリティ

- [must] label を省略する場合は aria-label を付与する

## 実装

- [should] 種類が決まっている入力には type を指定する（例：email、tel）
- [should] 利用者自身の情報を入力させる場合は autoComplete を指定する
- [should] 初期値は defaultValue（制御する場合は value と onChange）で指定する
- [should] エラーの文言は validate で返す。返した文言が入力欄の下に表示される
- [should] フォームで送信する場合は name を指定する

## Props（自動生成）

型定義から生成した props の一覧です。react-aria-components から引き継いだ props の説明は英語です。DOM の汎用的な属性・イベントは省略しています。

### TextField

| 名前 | 型 | 既定値 | 説明 |
|---|---|---|---|
| label | string | - | 入力フィールドのラベルテキスト |
| caption | string | - | ラベル下部の補足説明テキスト |
| placeholder | string | - | 未入力時のプレースホルダーテキスト |
| size | "s" \| "m" \| "l" | - | 入力フィールドのサイズ |
| width | "auto" \| "full" \| "half" \| "third" | - | 入力フィールドの幅 |
| color | "neutral" \| "negative" | - | 入力フィールドの色テーマ。negativeでエラー状態を表現 |
| component | "input" \| "textarea" | - | 入力要素の種類。textareaで複数行入力に対応 |
| validationBehavior | "native" \| "aria" | 'native' | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| aria-activedescendant | string | - | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. |
| aria-autocomplete | "none" \| "inline" \| "list" \| "both" | - | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made. |
| aria-haspopup | boolean \| "false" \| "true" \| "menu" \| "listbox" \| "tree" \| "grid" \| "dialog" | - | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| aria-controls | string | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| enterKeyHint | "enter" \| "done" \| "go" \| "next" \| "previous" \| "search" \| "send" | - | An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint). |
| isDisabled | boolean | - | Whether the input is disabled. |
| isReadOnly | boolean | - | Whether the input can be selected but not changed by the user. |
| isRequired | boolean | - | Whether user input is required on the input before form submission. |
| isInvalid | boolean | - | Whether the value is invalid. |
| validate | ((value: string) => true \| ValidationError \| null) | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| autoFocus | boolean | - | Whether the element should receive focus on render. |
| value | string | - | The current value (controlled). |
| defaultValue | string | - | The default value (uncontrolled). |
| onChange | ((value: string) => void) | - | Handler that is called when the value changes. |
| aria-label | string | - | Defines a string value that labels the current element. |
| aria-labelledby | string | - | Identifies the element (or elements) that labels the current element. |
| aria-describedby | string | - | Identifies the element (or elements) that describes the object. |
| aria-details | string | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| excludeFromTabOrder | boolean | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| id | string | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| autoComplete | string | - | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| maxLength | number | - | The maximum number of characters supported by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength). |
| minLength | number | - | The minimum number of characters required by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength). |
| pattern | string | - | Regex pattern that the value of the input must match to be valid. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern). |
| type | "search" \| "text" \| "url" \| "tel" \| "email" \| "password" \| (string & {}) | 'text' | The type of input to render. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype). |
| inputMode | "none" \| "search" \| "text" \| "url" \| "tel" \| "email" \| "numeric" \| "decimal" | - | Hints at the type of data that might be entered by the user while editing the element or its contents. See [MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute). |
| autoCorrect | string | - | An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete). |
| spellCheck | string | - | An enumerated attribute that defines whether the element may be checked for spelling errors. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck). |
| name | string | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| form | string | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| aria-errormessage | string | - | Identifies the element that provides an error message for the object. |
| style | StyleOrFunction<TextFieldRenderProps> | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| className | ClassNameOrFunction<TextFieldRenderProps> | - | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| slot | string \| null | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |