メインコンテンツへスキップ
menumenu tanreiexpand_morecontrasttranslate
tanreiexpand_more
はじめにWebReactSwiftUIJetpack ComposeFlutterReact Nativeプリセット自分のデザインシステムを作るAI エージェントと Tanrei を使うブランドデザイントークンデザインシステムとカスタマイズTheme Studioカラータイポグラフィアイコン形状エレベーションモーションインタラクション状態振る舞いレイアウトアクセシビリティ言葉カラートークンタイプスケールトークン形状トークンエレベーショントークンモーショントークン状態トークンスペースと寸法のトークンコンポーネントボタンメインアクションボタンセグメントボタンボタングループメニュー付きボタンツールバーコピーボタンチェックボックスラジオボタンスイッチチップメニュースライダースライダーフィールドカレンダーDateTimePickerフィールドグループラジオグループチェックボックスグループセレクトセレクトフィールドメニューバーファイルアップロードファイルピッカー 上級者向けドロップゾーンテキスト入力欄 上級者向けテキストフィールドチップフィールドフィールドコンボボックス 上級者向けコンボボックスフィールド数値入力欄 上級者向け数値フィールドカラー入力欄 上級者向けカラーフィールドワンタイムコード入力欄 上級者向けワンタイムコードフィールド埋め込みテキスト入力欄 上級者向けチャットコンポーザーカード区切り線モーダルレイヤー 上級者向けダイアログリストリスト行ボトムシートサイドシートカルーセルコードブロックテーブルポップオーバーステップアコーディオン説明リスト図アプリシェルページヘッダーツリービュータイムライン画像プレビューハンドルサイズ変更できる枠スクロールエリアバッジプログレスインジケーターメーターナンバーティッカーローディングインジケータースナックバーツールチップキーボードショートカットタグインラインコードコールアウトアバター空の状態タググループスケルトンファイル項目色見本マーキーテキストタブタブビューアプリバーナビゲーションバーナビゲーションドロワー検索リンクページネーション前後のリンクステッパーパンくずリスト目次リンクカードFAB メニューステータスTanrei の作り方コントリビューションライセンスと帰属
ホームコンポーネントテキストフィールド

テキストフィールド

1 行のテキスト、文章に合わせて伸びるか手で大きさを変えられる複数行のテキスト、ロケールの書き方で単位ごとに入力する日付・時刻、書かれたとおりに保持するコードを入力・編集します。必須か任意かを示せるラベル、アイコン、接頭辞と接尾辞、補足テキスト、文字数カウンター、ピッカーボタンを添えられます。

content_copyMarkdown で表示
カテゴリ
テキスト入力
トークン
comp.field
レベル
合成
構成要素
Field, Text input

概要

Web
tanrei-text-field
schedule
SwiftUI
TanreiTextField
schedule
Jetpack Compose
TanreiTextField
schedule
Flutter
TanreiTextField
schedule
React Native
TextField
schedule
提供しないバリアント
tanrei: filled, outlined

生成元 docs/status/status.json, specs/text-field.spec.json

仕様は改訂済み、各プラットフォームは追従待ち

このページは、仕様の現在の形のテキストフィールドを説明しています。ラベルをフィールドの上に置く stacked バリアントが既定で、filled と outlined は Material と cupertino のプリセットだけのものです。高さは 32、40、56（ラベルが中で浮き上がる filled と outlined のフィールドは 40、48、56）で、日付と時刻の種類とピッカーボタンがあります。複数行のフィールドは文章に合わせて伸びるか、ハンドルで大きさを変えられ（resize）、日付や時刻はセグメントで単位ごとに入力し、必須か任意かを示す required と optional があります。Web コンポーネントはすでにこのすべてに対応しており、デモもそれを示しています。フィールドはコードも保持できます（type="code" と、行の折り返しを決める wrap）。Web は実装済みで、ほかのプラットフォームはまだです。テキストフィールドは、このページで説明しているとおり、テキスト入力欄を囲むフィールドです。Web はこれも実装済みで、required 属性はなくなりました。SwiftUI、Compose、Flutter、React Native は上の表で「追従待ち」です。追従するまでは以前の版（既定が outlined で高さ 36 と 40、印を描かない required フラグがあり、stacked バリアント・日付や時刻の種類・ピッカーボタン・リサイズの方式はない）を提供しており、これらの例もその版のものです。

既定の Stacked：必須のフィールドと、ピッカーボタン付きの日付

テキストフィールドは、フォームがテキストを求めるところで使います。ラベル、ボックス、1 行の補足、値が違うときの言葉、文字数という、いつもの組み合わせが、そのまま使える形でそろっています。

構成要素は、フィールドとテキスト入力欄です。フィールドは枠で、ラベル、必須または任意の印、補足、エラー、文字数を受け持ちます。テキスト入力欄はコントロールで、ボックスと、その中で入力するものすべてを受け持ちます。テキストフィールドが自分で描くものはなく、トークンもありません。プロパティはどれも 2 つのどちらかのもので、そのまま渡されます。

置かれた場所の幅いっぱいに広がるブロックで、ボックスもその幅いっぱいになります。自分の幅は持ちません。フィールドを狭くするには、置く場所を狭くします。

プレイグラウンド

textemailpasswordnumbersearchtelurlcodedatetimedate-time
コントロールごとに、実際のコンポーネントのプロパティを 1 つ設定します。コードも合わせて変わります。設定はページのアドレスに残るので、リンクを開くと同じ状態で表示されます。 コードは Web 用です。ほかのプラットフォームは「プラットフォーム別の名前対応」を参照してください。

使い方

<form>
  <tanrei-text-field name="email" label="メールアドレス" type="email" autocomplete="email" required required-text="必須"
    supporting-text="サインインにだけ使います。"></tanrei-text-field>
  <tanrei-text-field name="company" label="会社名" optional optional-text="任意"></tanrei-text-field>
  <!-- 文章に合わせて 3 行から 8 行まで伸び、それを超えるとスクロールします。 -->
  <tanrei-text-field name="message" label="メッセージ" multiline min-rows="3" max-rows="8"></tanrei-text-field>
  <!-- ハンドルを使って、手で大きさを変えます。 -->
  <tanrei-text-field name="notes" label="メモ" multiline resize="manual" resize-label="メモの大きさを変える"></tanrei-text-field>
</form>

<!-- ツールバーに置くボックスだけのもの：自身の label で名前を付けたテキスト入力欄です。テキストフィールドをインポートすると定義されます。 -->
<tanrei-text-input label="検索" type="search" placeholder="コンポーネントを検索">
  <span slot="leading-icon">search</span>
</tanrei-text-input>

<!-- コード：ページの向きにかかわらず左から右へ、コード用の書体で描きます。自動修正もスペルチェックもしません。 -->
<tanrei-text-field label="パターン" type="code" value="tanrei.comp.button.*.container.color"></tanrei-text-field>
<tanrei-text-field label="Webhook の本文" type="code" multiline min-rows="4" supporting-text="JSON"></tanrei-text-field>
<!-- 折り返しません。コードの 1 行は 1 行のままで、長い行はフィールドの中で横にスクロールします。 -->
<tanrei-text-field label="行" type="code" multiline no-wrap></tanrei-text-field>

<!-- ロケールの順に単位ごとに入力し、2026-09-27 の形で保持する日付。ピッカーボタン付き。 -->
<tanrei-text-field id="start" label="開始日" type="date" min="2026-01-01" disabled-dates="2026-05-01 2026-12-25"
  invalid-text="日付を最後まで入力してください。" unavailable-text="2026 年以降の営業日を選んでください。"
  picker picker-label="開始日を選択" segment-empty-text="未入力"></tanrei-text-field>
<tanrei-date-time-picker id="start-picker" presentation="docked" anchor="start" label="開始日"></tanrei-date-time-picker>

<script type="module">
  import '@tanrei/web/components/text-field';
  const email = document.querySelector('[name="email"]');
  email.addEventListener('input', () => draft(email.value)); // 編集のたびに
  email.addEventListener('change', () => save(email.value)); // 値が変わった状態でフォーカスが外れたか、Enter を押したとき
  // 検証は利用者側で行います。フィールドが自分で error を設定することはありません。
  email.error = submitted && !isValid(email.value);
  email.errorText = 'メールアドレスを最後まで入力してください。';

  // フィールドは依頼するだけです。ピッカーを表示し、値を書き戻すのはプロダクト側です。
  const start = document.querySelector('#start');
  const picker = document.querySelector('#start-picker');
  start.addEventListener('pickerrequest', (e) => {
    Object.assign(picker, { value: e.detail.value, min: e.detail.min, max: e.detail.max, disabledDates: start.disabledDates, open: true });
  });
  picker.addEventListener('change', () => (start.value = picker.value));
  picker.addEventListener('close', () => (picker.open = false));
</script>
 
import { TextField } from '@tanrei/react';

<TextField
  label="メールアドレス"
  type="email"
  autocomplete="email"
  value={email}
  onInput={(e) => setEmail(e.currentTarget.value)}
  onChange={() => save(email)}
  required
  requiredText="必須"
  error={submitted && !isValid(email)}
  errorText="メールアドレスを最後まで入力してください。"
/>

<TextField label="メッセージ" multiline minRows={3} maxRows={8} value={message}
  onInput={(e) => setMessage(e.currentTarget.value)} />

// 日付：値は ISO 8601 で、空のセグメントがあるあいだは空です。
<TextField
  label="開始日"
  type="date"
  min="2026-01-01"
  value={start}
  invalidText="日付を最後まで入力してください。"
  unavailableText="2026 年以降の日付を選んでください。"
  segmentEmptyText="未入力"
  picker
  pickerLabel="開始日を選択"
  onChange={(e) => setStart(e.currentTarget.value)}
  onEntryError={(e) => report(e.detail.reason)}
  onPickerRequest={() => setPickerOpen(true)}
/>
 
import Tanrei

TanreiTextField("メールアドレス", text: $email, type: .email,
                supportingText: "サインインにだけ使います。",
                errorText: "メールアドレスを最後まで入力してください。",
                error: submitted && !isValid(email),
                textContentType: "email", // HTML の自動入力名
                onCommit: save,
                // 実行はここに渡します。外側の .onSubmit は onCommit より先に呼ばれます。
                onSubmit: signIn)

// 複数行は縦方向の axis と、行数の範囲を指定した lineLimit で表します。
TanreiTextField("メッセージ", text: $message, axis: .vertical, lineLimit: 3...8)
 
import androidx.compose.foundation.text.KeyboardActions
import io.github.chnotchy.tanrei.components.TanreiTextField
import io.github.chnotchy.tanrei.components.TanreiTextFieldType

var email by remember { mutableStateOf("") }
TanreiTextField(
    value = email,
    onValueChange = { email = it },
    label = "メールアドレス",
    type = TanreiTextFieldType.Email,
    contentType = "email", // HTML の自動入力名
    supportingText = "サインインにだけ使います。",
    isError = submitted && !isValid(email),
    errorText = "メールアドレスを最後まで入力してください。",
    onCommit = { save(it) },
    keyboardActions = KeyboardActions(onDone = { signIn() }),
)

// singleLine は仕様の multiline の逆です。
TanreiTextField(value = message, onValueChange = { message = it }, label = "メッセージ", singleLine = false, minLines = 3)
 
import 'package:tanrei/tanrei.dart';

TanreiTextField(
  controller: email, // または initialValue: '…'
  labelText: 'メールアドレス',
  type: TanreiTextFieldType.email,
  autofillHints: TanreiTextField.autofillHintsFromHtml('email'),
  helperText: 'サインインにだけ使います。',
  isError: submitted && !isValid(email.text),
  errorText: 'メールアドレスを最後まで入力してください。',
  onCommit: save,
  onSubmitted: (String value) => signIn(),
);

TanreiTextField(labelText: 'メッセージ', multiline: true, minLines: 3);
 
import { TextField } from '@tanrei/react-native';

<TextField
  label="メールアドレス"
  type="email"
  autoComplete="email"
  value={email}
  onChangeText={setEmail}
  supportingText="サインインにだけ使います。"
  error={submitted && !isValid(email)}
  errorText="メールアドレスを最後まで入力してください。"
  onEndEditing={save}
  onSubmitEditing={signIn}
/>
<TextField label="メッセージ" multiline minRows={3} value={message} onChangeText={setMessage} />

1 つ下の階層

同じフィールドを 2 つの構成要素から自分で書いても、見た目は同じで、支援技術にとっても、同じ名前、説明、状態を持つ同じテキストボックスになります。

<tanrei-field label="メールアドレス" required required-text="必須"
  supporting-text="サインインにだけ使います。">
  <tanrei-text-input name="email" type="email" autocomplete="email"></tanrei-text-input>
</tanrei-field>

同じフィールドを自分で書いたもの。フィールドの中にテキスト入力欄があります

テキストフィールドにない並べ方が必要なときに、1 つ下の階層で書きます。

必要なもの 使うもの
ラベル、ボックス、補足、エラー、文字数 テキストフィールド
枠の中、ボックスの横か下に置く自分の要素 フィールドに、テキスト入力欄と自分の要素を入れる
ボックスだけ。ラベルは別の場所にある（ツールバーの絞り込み、テーブルのセル、ラベルを横に置いた行） テキスト入力欄を単独で使い、入力欄の label で名前を付ける

1 つ下の階層で変わるのは、何をどこに指定するかです。name と value はテキスト入力欄に指定し、フォームに加わるコントロールもイベントが届く先も入力欄になります。label、error、disabled、必須の指定はフィールドに指定したままにします。フィールドがコントロールに伝えるので、入力欄の側には指定しません。

テキストフィールドが行い、フィールドとテキスト入力欄を自分で書いたものが行わないことが 1 つあります。文字数を合わせ続けることです。自分で書く場合、counter を付けたら、値が変わるたびに入力欄の文字数をフィールドに渡します。

field.countText = input.countText;
input.addEventListener('input', () => (field.countText = input.countText));

仕様

エラー、無効、読み取り専用、接頭辞と接尾辞、カウンター

種類：パスワード、検索、数値、電話番号、URL

search

必須と任意：タグと、アスタリスク

複数行：文章に合わせて伸びる、ハンドルで変える（縦、縦横）、固定

コード：1 行のパターン、複数行の JSON、折り返さない行

右から左のページのコード：ラベルと補足はページに従い、コードは左から始まる

セグメントで入力する日付、時刻、日時。Tab、矢印キー、数字で埋めます

Material のプリセットのバリアント、Filled と Outlined

m3-like で表示

それぞれの構成要素が受け持つもの

観点 フィールドから テキスト入力欄から
プロパティ label、labelHidden、supportingText、errorText、error、disabled、required、optional、requiredMark、requiredText、optionalText それ以外のすべて。variant、size、type、value、placeholder、readOnly、複数行とリサイズ、wrap、maxLength、counter、接頭辞と接尾辞、autocomplete、日付と時刻に関するすべて
イベント — input、change、action、pickerRequest、entryError
スロット label-icon leading-icon、trailing-icon
トークン comp.field.* ボックスは comp.input-box.*（すべての入力ボックスが読みます）。テキスト入力欄だけが描く部分は comp.text-input.*

テキスト入力欄は、自分の label、labelHidden、error、disabled を持っています。テキストフィールドが設定するのは、それらではありません。テキストフィールドの label はフィールドのもので、入力欄に名前を付け、Filled と Outlined のフィールドではボックスの中で浮き上がるラベルになります。

トークン

テキストフィールドに自分のトークンはありません。ボックスはテキスト入力欄のトークンを、行（ラベル、印、補足、エラー、文字数）はフィールドのトークンを、どこで設定されていても読みます。下の表にあるのはフィールドのトークンです。1 つだけ変えるには、構成要素のトークンをその要素に設定します。

<tanrei-text-field label="メールアドレス"
  style="--tanrei-comp-field-label-gap: 12px"></tanrei-text-field>

構成要素

構成要素

Web パッケージが描くフィクスチャ outlined-empty の上に描いています。
パーツ 説明
1 field The Field: the label row with its glyph and its requirement mark, and the supporting row with the help, the error text and the count the text field gives it (TXF-67). In a look whose input floats the label it draws no label row.
2 text-input The text input, as the Field's one control: the box and everything typed in it, the icons, the prefix and the suffix, the segments of a date, the picker button, the resize handle, and the label that floats in the box in the looks that float one.

プロパティ

プロパティ 型 既定値 説明
variant stacked | filled | outlined "stacked" Stacked is a filled box that shows focus and error with a line inside its edge and draws no label: the label of the Field that frames it stands above it. Filled and outlined float the label inside the box, marked by a tinted box and a bottom line, or by a border. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. — Text input
size small | medium | large "medium" Minimum height of a single-line input's container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that an input and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. Medium and large are for forms; small is for an input in an app bar, a toolbar or a dense row of controls, beside a small select or button. The hit area always meets the minimum target. — Text input
type text | email | password | number | search | tel | url | code | date | time | date-time "text" What the value is: chooses the keyboard, autocorrection, obscured entry and semantics. code is text written for a machine rather than for a reader — a snippet of configuration, a pattern, an identifier, a query, a key: a left-to-right run in the code face that the platform does not correct, capitalise, check for spelling or complete, on one line or, with multiline, on many. date, time and date-time are entered segment by segment in the locale's numeric form and held as ISO 8601. The value is a string for every type. — Text input
value string "" The text in the field; for date, time and date-time, the ISO 8601 form of what its segments give (2026-09-27, 14:30, 2026-09-27T14:30), or empty while a segment is empty or the value is not available. — Text input
label string "" Names the control, visibly and to assistive technology. Required, unless the control names itself (a checkbox or a switch with its own label): then leave it empty and the field adds only help and an error. — Field Names the text input. In a filled or outlined look the input draws it, floating in its box, and the Field draws no label row (FLD-25, TXI-13).
labelHidden boolean false Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). — Field Hides the label wherever it would be drawn: the Field's row, or the input's floating label (FLD-25).
placeholder string "" A hint shown while the value is empty and the label is not in the input line (above, floated or hidden). Never a replacement for label. In a code field it is an example of the code and is drawn as code (TXI-53, TXI-54); a hint in words belongs in the supportingText of its Field. Ignored by a date, time or date-time field, whose empty segments each show their own. — Text input
supportingText string "" Help shown below the control and given to assistive technology as the control's description. While the field is in error it gives way to errorText, unless the design system keeps both (comp.field.error-text.placement append). — Field
errorText string "" Shown while error is true, in supportingText's place — or below it, which then stays, where the design system's comp.field.error-text.placement is append: what is wrong and how to put it right, in words. — Field
error boolean false Puts the field in the error condition: the error text is drawn, the control is exposed as invalid and, where it has an error condition of its own, drawn in it. What a value means is the product's to validate; the field never sets this itself. — Field The Field puts its text input in the input's own error condition (FLD-8, TXI-11).
disabled boolean false Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. — Field The Field disables its text input (FLD-14, TXI-5); the text field is then left out of its form (TXF-63).
readOnly boolean false The value can be focused, selected and copied, but not changed. — Text input
required boolean false What the form asks of the control: true exposes it as required and draws the required mark beside the label. It never validates: a missing answer is the product's to report with error. — Field The Field exposes its text input as required (FLD-10, TXI-23).
optional boolean false Draws the optional tag after the label and adds optionalText to the control's description, because assistive technology has no state for it. Ignored while required is true: a control is never both. — Field
requiredMark auto | tag | asterisk | none "auto" How this control shows that it is required: tag is a small filled Tag with requiredText, asterisk is "*" after the label, none draws nothing and keeps the semantics. Auto takes comp.field.requirement.mark, which follows sys.behavior.requirement-mark, the system's one answer. Ignored unless required is true. — Field
requiredText string "" The text of the required tag, in the product's language ("Required", "必須"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, FLD-24 says what is drawn. — Field
optionalText string "" The text of the optional tag, in the product's language ("Optional", "任意"); also read to assistive technology as part of the description. The product's: Tanrei has no word for it. Empty reads the product's words. — Field
multiline boolean false Accepts line breaks and shows several lines, sized as resize says. Ignored for password, date, time and date-time. — Text input
minRows number 2 The fewest lines a multi-line field shows: the height of an empty auto-resized field, the starting and smallest height of a manually resized one, and the height of a fixed one. — Text input
maxRows number 0 The most lines an auto-resized field grows to before it scrolls, and the tallest a manually resized one can be made; 0 is no limit. Ignored while resize is fixed. — Text input
resize auto | manual | fixed "auto" How a multi-line field gets its height. auto: it follows the number of lines between minRows and maxRows, with an animated change, and has no handle. manual: it starts at minRows lines and the person resizes it with the handle in its bottom end corner. fixed: it stays at minRows lines, with no handle. Ignored unless multiline. — Text input
resizeAxis vertical | both "vertical" What the person can resize by hand: the height only, or the height and the width. Ignored unless resize is manual. — Text input
resizeLabel string "" The accessible name of the resize handle, in the product's language ("Resize"). The product's: Tanrei has no word for it. Empty reads the product's words. Required while the handle is shown. — Text input
wrap boolean true Whether a multi-line code field continues a line that does not fit on following rows (true), or keeps every line of the code on one row and scrolls sideways inside its container (false) — for code whose lines are read as rows: a table of values, a log, a file in which a line break means something. The value is the same either way. Ignored unless type is code and multiline is true: prose always wraps, and a single line always scrolls in its line. — Text input
maxLength number 0 The most user-perceived characters the user can enter; 0 is no limit. Ignored for date, time and date-time. — Text input
counter boolean false Keeps the character count (and maxLength, when set): part of the input's description and announced when typing pauses (TXI-19). The input draws none: a text field gives the count to its Field, which draws it at the end of its supporting row, and a product that frames the input by hand gives it to the Field's countText. — Text input The input keeps the count, the text field gives it to its Field, and the Field draws it (TXI-19, TXF-67, FLD-27).
counterText string "" The count said to assistive technology while counter is true and maxLength is greater than 0: the whole sentence in the product's language with three places the input fills — {count} with the characters entered, {limit} with maxLength and {remaining} with how many more can be entered ("{remaining} characters left", "{limit}文字中{count}文字"). Empty reads the product's words; with neither, the count is said as the digits it is drawn in ("12/40"). A sentence that is right for every number, or a prop set per count where the language needs another form for one. — Text input
counterNoLimitText string "" The count said to assistive technology while counter is true and maxLength is 0: the whole sentence with one place, {count}, filled with the characters entered ("{count} characters", "{count}文字"). Empty reads the product's words; with neither, the count is said as its digits. — Text input
prefixText string "" Fixed text before the value, not part of it. In a code field it is code: drawn in the code face at the left of the value in every layout direction (TXI-53). — Text input
suffixText string "" Fixed text after the value, not part of it. In a code field it is code: drawn in the code face at the right of the value in every layout direction (TXI-53). — Text input
autocomplete string "" The autofill hint, as an HTML autofill field name (email, current-password, new-password, one-time-code, tel, postal-code, …); each platform maps it to its own content type. A code field left without one asks the platform to offer no remembered entry (TXI-55). — Text input
locale string "" A BCP 47 language tag ("en-US", "ja-JP") for how a date, time or date-time field shows and reads its value: the order of the year, month and day segments, the separators, the clock, the digits and the names of the units. Empty uses the platform's current locale. The calendar is the Gregorian calendar in every locale. — Text input
min string "" The earliest value a date, time or date-time field accepts from the person, in its ISO 8601 form; empty for no limit. — Text input
max string "" The latest value a date, time or date-time field accepts from the person, in its ISO 8601 form; empty for no limit. — Text input
disabledDates strings Dates inside min and max that a date or date-time field does not accept from the person, as ISO 8601 calendar dates — the same list the product gives its DateTimePicker. Ignored by a time field. — Text input
invalidText string "" The words for a date, time or date-time input committed with some segments filled and others empty: given to the Field that frames it, which shows them as its error text (TXI-30). — Text input Shown by the Field, in its supporting row (FLD-28).
unavailableText string "" The words for a date, time or date-time input committed with a value before min, after max or, for a date, listed in disabledDates: given to the Field that frames it, which shows them as its error text (TXI-30). — Text input Shown by the Field, in its supporting row (FLD-28).
segmentEmptyText string "" What assistive technology reads as the value of a date or time segment that holds nothing yet, in the product's language ("Empty"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, an empty segment has no value text. — Text input
picker boolean false Shows the picker button in a date, time or date-time field. The field presents no picker itself: it emits pickerRequest, and the product presents a DateTimePicker in the matching mode and sets value to what was picked. — Text input
pickerLabel string "" The accessible name of the picker button ("Choose date"). Required while picker is shown. — Text input

スロット

スロット 説明
leading-icon An icon at the start of the input. — Text input
trailing-icon An icon at the end of the input, or the product's own icon-only Button (clear, reveal password). A date or time field's picker button comes after it. — Text input
label-icon A glyph before the label. — Field

イベント

イベント 説明
input The user changed the value; carries the new value. Emitted for every change, not when the product sets value. A date, time or date-time field emits it when its value changes — when its last segment is filled, a filled field is edited, or it is emptied — not for a segment that leaves the value empty. — Text input
change The user committed a changed value (focus left the field, or the action key was pressed in a single-line field); carries the value. — Text input
action The user pressed the keyboard's action key (Enter, Return, Go, Search, Done) in a single-line field. — Text input
pickerRequest The user activated the picker button of a date, time or date-time field; carries the value, type, min and max. The product presents the picker and sets value to the picked value. — Text input
entryError The user committed a date, time or date-time field that is half-filled or whose value is not available; carries the reason (invalid: some segments are empty; unavailable: before min, after max or a listed date) and the text of the row of segments as drawn. The entry error itself is shown by the Field that frames the input (TXI-30). — Text input
resizeEnd The person finished changing the size of a field resized by hand: a drag of its handle ended, or a key or an activation of the handle changed the size (TXI-69). Carries lines, the number of lines the input shows, and width, the field's width in pixels WHILE resizeAxis is both (null otherwise). Not emitted when a change of resize, resizeAxis, minRows or maxRows gives the size back. — Text input

状態

振る舞い

EARS 記法による要件です。各プラットフォームの実装は、この ID に対応するテストで検証されます。要件の原文は仕様ファイルのものをそのまま掲載しています。

ID 要件
TXF-62 THE text field SHALL be a Field that frames one text input, and nothing else. It SHALL give label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText to its Field and every other prop to its text input, each unchanged; SHALL hold the label-icon slot for its Field and the leading-icon and trailing-icon slots for its text input; and SHALL emit its text input's events as its own, each once. THE text field SHALL be as wide as the place it stands in, and its text input SHALL fill it: it is a block with no width of its own, as its Field is (FLD-1), around a control that fills the width it is given (TXI-63). It SHALL draw no part of its own, have no token of its own and hold no state of its own but the count it carries from one member to the other (TXF-67): what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that text input do when a product places the one in the other (FLD-1 to FLD-28; TXI-1 to TXI-63), with the Field given the input's count — the label row and its requirement mark (FLD-2 to FLD-6), or the label that floats in the box with the Field's row left out (FLD-25, TXI-13, TXI-50); the supporting row, the error and the count (FLD-7 to FLD-9, FLD-26, FLD-27, TXI-19, TXF-67); the name, the description and the states (FLD-10, FLD-11, FLD-14, TXI-23); and a date's entry error shown in the Field's row (FLD-28, TXI-30).
TXF-63 WHERE the platform has forms (the web) THE text field SHALL be the one control the form sees: it SHALL take name, submit its text input's value, reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its text input would report there (TXI-23, TXI-30), and be left out WHILE disabled is true or a disabled group of the form holds it; its text input and its Field SHALL take no part in the form themselves. WHEN the action key asks for the form's submission (TXI-3) the form asked SHALL be the text field's own.
TXF-64 WHEN the text field is given focus — by the product, by a press on any part of it that FLD-12 or TXI-8 gives to the input, or by a form that reports its validity — THE text field SHALL pass the focus to its text input (in a date, time or date-time field, to the segment TXI-43 names) and SHALL add no stop to the focus order: the stops inside it are its text input's, in that input's order (an interactive slot element, the picker button, the resize handle). WHILE focus is anywhere inside it THE text field SHALL count as focused for its Field (FLD-13).
TXF-65 IF the text field is placed in a Field THE text field SHALL in debug builds report that it is a field already and that the bare control is the text input, and both SHALL still render (FLD-15). WHILE it stands in a field group THE text field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20).
TXF-66 THE text field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), resizeLabel and segmentEmptyText by its text input (TXI-52), each from the instance's prop and then from the product's words.
TXF-67 WHILE counter is true THE text field SHALL give its Field, as its count text (FLD-27), the count its text input keeps (TXI-19), as the input writes it, and SHALL give the new one in the same frame in which the value changes — by typing, by a paste, because the product set value or maxLength — without a motion and without an announcement of its own: the input describes and announces its count itself (TXI-19) and the Field keeps the drawn text from assistive technology (FLD-27). WHILE counter is false THE text field SHALL give its Field no count text. THE text field SHALL NOT count, format or write a digit itself.
TXF-68 WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE text field SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the text field is invalid — except those the text field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (TXF-62). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE text field SHALL take it off that element. WHEN the product sets an aria- attribute the text field owns THE text field SHALL report it in debug builds.

プラットフォーム別の名前対応

パリティは API が同一であることを意味しません。同じ契約を、各プラットフォームの流儀で表現します。

仕様 Web SwiftUI Jetpack Compose Flutter React Native
コンポーネント tanrei-text-field TanreiTextField TanreiTextField TanreiTextField TextField
variant · プロパティ variant variant variant variant variant
size · プロパティ size size size size size
type · プロパティ type type type type type
value · プロパティ value text value controller value
label · プロパティ label label label labelText label
labelHidden · プロパティ labelHidden labelsHidden labelHidden labelHidden labelHidden
placeholder · プロパティ placeholder prompt placeholder hintText placeholder
supportingText · プロパティ supportingText supportingText supportingText helperText supportingText
errorText · プロパティ errorText errorText errorText errorText errorText
error · プロパティ error error isError isError error
disabled · プロパティ disabled disabled enabled enabled disabled
readOnly · プロパティ readOnly readOnly readOnly readOnly readOnly
required · プロパティ required isRequired required required required
optional · プロパティ optional isOptional optional optional optional
requiredMark · プロパティ requiredMark requiredMark requiredMark requiredMark requiredMark
requiredText · プロパティ requiredText requiredText requiredText requiredText requiredText
optionalText · プロパティ optionalText optionalText optionalText optionalText optionalText
multiline · プロパティ multiline axis singleLine multiline multiline
minRows · プロパティ minRows lineLimit minLines minLines minRows
maxRows · プロパティ maxRows lineLimit maxLines maxLines maxRows
resize · プロパティ resize resize resize resize resize
resizeAxis · プロパティ resizeAxis resizeAxis resizeAxis resizeAxis resizeAxis
resizeLabel · プロパティ resizeLabel resizeLabel resizeContentDescription resizeSemanticLabel resizeAccessibilityLabel
wrap · プロパティ noWrap wrap softWrap softWrap wrap
maxLength · プロパティ maxLength maxLength maxLength maxLength maxLength
counter · プロパティ counter counter counter showCounter counter
counterText · プロパティ counterText counterText counterText counterSemanticText counterAccessibilityText
counterNoLimitText · プロパティ counterNoLimitText counterNoLimitText counterNoLimitText counterNoLimitSemanticText counterNoLimitAccessibilityText
prefixText · プロパティ prefixText prefix prefix prefixText prefix
suffixText · プロパティ suffixText suffix suffix suffixText suffix
autocomplete · プロパティ autocomplete textContentType contentType autofillHints autoComplete
locale · プロパティ locale locale locale locale locale
min · プロパティ min min min min min
max · プロパティ max max max max max
disabledDates · プロパティ disabledDates disabledDates disabledDates disabledDates disabledDates
invalidText · プロパティ invalidText invalidText invalidText invalidText invalidText
unavailableText · プロパティ unavailableText unavailableText unavailableText unavailableText unavailableText
segmentEmptyText · プロパティ segmentEmptyText segmentEmptyText segmentEmptyText segmentEmptyText segmentEmptyText
picker · プロパティ picker onPickerRequest onPickerRequest onPickerRequest onPickerRequest
pickerLabel · プロパティ pickerLabel pickerLabel pickerContentDescription pickerSemanticLabel pickerAccessibilityLabel
input · イベント input text onValueChange onChanged onChangeText
change · イベント change onCommit onCommit onCommit onEndEditing
action · イベント action onSubmit keyboardActions onSubmitted onSubmitEditing
pickerRequest · イベント pickerrequest onPickerRequest onPickerRequest onPickerRequest onPickerRequest
entryError · イベント entryerror onEntryError onEntryError onEntryError onEntryError
resizeEnd · イベント resizeend onResizeEnd onResizeEnd onResizeEnd onResizeEnd
備考 The tag is tanrei-text-field, the class TanreiTextField, the React name TextField. Members: <tanrei-field> holding one <tanrei-text-input> in its default slot; the product places none. The host is display: block, as wide as its place, and the input fills it (TXF-62). Value member: tanrei-text-input. The host is the form's element — name, the value and its state, validity anchored on the input, reset to the value attribute, restore, form, a disabled fieldset — and the input inside has no name. Props, set as properties on the member each is from. On the Field: label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText, optionalText. On the text input: variant, size, type, value, placeholder, readOnly, multiline, minRows, maxRows, resize, resizeAxis, resizeLabel, noWrap (the inverse of wrap, attribute no-wrap), maxLength, counter, prefixText, suffixText, autocomplete, locale, min, max, disabledDates, invalidText, unavailableText, segmentEmptyText, picker, pickerLabel. Attributes are the members' own: kebab-case, except readonly, maxlength, autocomplete, min and max. Props of one name on both members — label, labelHidden, error, disabled — are the Field's; the input's are never set by the element and reach the input through the connection. Events: input, change, action, pickerrequest, entryerror are the text input's own composed events and leave by themselves, with the host as their target and value already new; action stays cancelable. None is stopped and none is copied. Slots: label-icon is passed to the Field, leading-icon and trailing-icon to the text input, each by a slot element of the same name rendered only while the host has a child for it; the product's own Button in trailing-icon stays the product's element. Parts: the member hosts are field and text-input. Exported from the Field: label, label-icon, requirement-label, supporting-text, counter. Exported from the text input: container, outline, active-indicator, label, requirement-label, input, segment, prefix, suffix, leading-icon, trailing-icon, picker-button, resize-handle. Two names collide, label and requirement-label. Each is exported with its member's name before it, always (field-label, text-input-label, field-requirement-label, text-input-requirement-label), and under the bare name from both members as well, because the two are one thing to a person and are never drawn at once: FLD-25 is the sentence that holds it — while its control draws the label itself the Field draws no label row and no requirement tag, and a stacked input draws neither (TXI-13, TXI-50). So tanrei-text-field::part(label) keeps meaning the drawn label. Focus: the shadow root does not delegate. focus() and blur() call the text input's; a press on the label row — the label, its glyph, the requirement mark — focuses the input by FLD-12, the Field's own sentence (the Field calls focus() on its control, which stands beside it in the same tree); a press on the box, and on a label that floats in it, by TXI-8; and a press on the supporting row — the help, the error text, the count — or on the gap between a row and the box does nothing (FLD-12). The connection is the Field's with its control, in both directions (FLD-25, FLD-26, FLD-28, TXI-62); the element takes no part in it. A member's prop it sets itself (fills): the Field's countText, from the text input's read-only countText after each of the input's updates, in the same task (TXF-67). Parts and tokens of its own: none. The element writes no custom property: --tanrei-comp-field-*, --tanrei-comp-input-box-* and --tanrei-comp-text-input-* reach the members by inheritance, and one text field is set apart by setting any of them on the element. What its twin cannot do that it does: keep the Field's count text equal to the input's count as the person types (TXF-67); nothing else. The twin: <tanrei-field label="Email" supporting-text="We never share your address." required><tanrei-text-input name="email" type="email" autocomplete="email"></tanrei-text-input></tanrei-field>. Its Field draws the help and the error text together (FLD-7, FLD-31), and the five fixtures *-supporting-error* hold the pair to its twin. Lagging: this platform draws the text field as one view that draws its own frame, written against the token group comp.text-field, which the tokens do not have. It owes, first, its sources moved to the generated names of comp.input-box, comp.text-input and comp.field: they do not compile until then. Then the split: the text input as a view of its own, and the text field as the Field around it. Its names and its props stay. What it does today: text: Binding<String> (as TextField); every edit writes the binding, which is the input event. password draws a SecureField; multiline is TextField(axis: .vertical) with .lineLimit(minRows...maxRows) — not TextEditor, which has no prompt and does not grow. labelHidden follows the .labelsHidden() environment; disabled follows .disabled(_:); action is the onSubmit: parameter, called after the commit (TXI-3); an enclosing .onSubmit modifier still fires, but before the commit, because SwiftUI runs the outer handler first. onCommit is Tanrei's own parameter (SwiftUI deprecated its own), called when focus leaves with a changed value. type maps to .keyboardType, .textInputAutocapitalization, .autocorrectionDisabled and .submitLabel; autocomplete maps HTML names to UITextContentType. locale follows the \.locale environment when not given. The picker button is shown when an onPickerRequest: closure is given (a nil closure is picker false); the product presents the picker and writes the binding. Not built on this platform yet: the optional flag (optional) beside the required flag; the resize modes and the handle (TXI-37–TXI-41, TXI-69), the segmented date and time row (TXI-42–TXI-47) and the requirement label (FLD-4, FLD-5, TXI-50). The platform proposes its own idiom for the segments when it catches up — each unit focusable and adjustable on its own, with the same value and events. Not built on this platform yet: the words props have no defaults, and the product's words are read from the \.tanreiWords environment value. Not built on this platform yet, for type code: .autocorrectionDisabled(), .textInputAutocapitalization(.never), .keyboardType(.asciiCapable), a monospaced design of the input's size, and .environment(\.layoutDirection, .leftToRight) on the input row alone; smart quotes, smart dashes and smart insert and delete are traits of the UIKit and AppKit text view (smartQuotesType, smartDashesType, smartInsertDeleteType, isAutomaticQuoteSubstitutionEnabled), so a code field is drawn on that view where SwiftUI's TextField gives no access to them; wrap: false needs that view too (a text container that does not track the view's width, in a scroll view), because TextField(axis: .vertical) always wraps. Not built on this platform yet: the count said as the product's sentence (counterText, counterNoLimitText, TXI-19); today the digits are said. Not built on this platform yet: comp.field.error-text.placement — the error text takes the help's place under every system, which is replace, the default; append, which keeps the help and draws the error text below it, is not drawn (FLD-7, FLD-31). Not built on this platform yet: size small (40), and in a right-to-left layout the value of an always left-to-right type beside its prefix (TXI-67). Lagging: this platform draws the text field as one view that draws its own frame, written against the token group comp.text-field, which the tokens do not have. It owes, first, its sources moved to the generated names of comp.input-box, comp.text-input and comp.field: they do not compile until then. Then the split: the text input as a view of its own, and the text field as the Field around it. Its names and its props stay. What it does today: Compose idiom (as TextField): value / onValueChange, with a TextFieldValue overload for products that manage selection and composition themselves; enabled and singleLine are inverse flags; isError, readOnly, minLines, maxLines, prefix and suffix keep Compose's names. Built on BasicTextField. type maps to KeyboardOptions (keyboard type, capitalization, autocorrect, IME action) and, for password, PasswordVisualTransformation; autocomplete maps to ContentType semantics. onCommit is Tanrei's own callback, called when focus leaves with a changed value or the IME action commits. locale defaults to the current configuration's locale. The picker button is shown when onPickerRequest is not null (null is picker false); pickerContentDescription follows Compose's naming for an icon's accessible name. Not built on this platform yet: the optional flag (optional) beside the required flag; the resize modes and the handle (TXI-37–TXI-41, TXI-69), the segmented date and time row (TXI-42–TXI-47) and the requirement label (FLD-4, FLD-5, TXI-50). The platform proposes its own idiom for the segments when it catches up — each unit focusable and adjustable on its own, with the same value and events. Not built on this platform yet: the words props have no defaults, and the product's words are read from LocalTanreiWords. Not built on this platform yet, for type code: KeyboardOptions(capitalization = KeyboardCapitalization.None, autoCorrectEnabled = false, keyboardType = KeyboardType.Ascii), TextStyle(textDirection = TextDirection.Ltr, textAlign = TextAlign.Left, fontFamily = …, fontFeatureSettings = "liga 0") on the input row inside CompositionLocalProvider(LocalLayoutDirection provides LayoutDirection.Ltr); softWrap = false puts the BasicTextField in a horizontalScroll that follows the cursor's rectangle. Not built on this platform yet: the count said as the product's sentence (counterText, counterNoLimitText, TXI-19); today the digits are said. Not built on this platform yet: comp.field.error-text.placement — the error text takes the help's place under every system, which is replace, the default; append, which keeps the help and draws the error text below it, is not drawn (FLD-7, FLD-31). Not built on this platform yet: size small (40), and in a right-to-left layout the value of an always left-to-right type beside its prefix (TXI-67). Lagging: this platform draws the text field as one view that draws its own frame, written against the token group comp.text-field, which the tokens do not have. It owes, first, its sources moved to the generated names of comp.input-box, comp.text-input and comp.field: they do not compile until then. Then the split: the text input as a view of its own, and the text field as the Field around it. Its names and its props stay. What it does today: Flutter idiom (as TextField and InputDecoration): the value lives in a TextEditingController (or an internal one with initialValue); labelText, hintText, helperText, errorText, prefixText, suffixText, minLines, maxLines, maxLength, readOnly, enabled and autofillHints keep Flutter's names, enabled being the inverse flag. isRequired and showCounter avoid Dart's required keyword and Flutter's own counter, which Tanrei replaces (it counts grapheme clusters with characters). maxRows: 0 is maxLines: null. type maps to keyboardType, obscureText, autocorrect, textCapitalization and textInputAction. onCommit is Tanrei's own callback, called when focus leaves with a changed value. locale defaults to Localizations.localeOf(context). The picker button is shown when onPickerRequest is not null (null is picker false). Not built on this platform yet: the optional flag (optional) beside the required flag; the resize modes and the handle (TXI-37–TXI-41, TXI-69), the segmented date and time row (TXI-42–TXI-47) and the requirement label (FLD-4, FLD-5, TXI-50). The platform proposes its own idiom for the segments when it catches up — each unit focusable and adjustable on its own, with the same value and events. Not built on this platform yet: the words props have no defaults, and the product's words are read from the TanreiWords inherited widget, which the app fills from its own localizations. Not built on this platform yet, for type code: autocorrect: false, enableSuggestions: false, textCapitalization: TextCapitalization.none, smartDashesType: SmartDashesType.disabled, smartQuotesType: SmartQuotesType.disabled, spellCheckConfiguration: const SpellCheckConfiguration.disabled(), textDirection: TextDirection.ltr, textAlign: TextAlign.left, a TextStyle with the code family and fontFeatures: [FontFeature.disable('liga')], the input row in a Directionality(textDirection: TextDirection.ltr); softWrap: false is an EditableText of unbounded width in a horizontal Scrollable that keeps the caret in view, because a multi-line TextField always wraps. Not built on this platform yet: helperText stays while the field is in error and errorText is drawn below it (FLD-7, FLD-31), unlike InputDecoration; today the error text takes the help's place. Not built on this platform yet: the count said as the product's sentence (counterText, counterNoLimitText, TXI-19); today the digits are said. Not built on this platform yet: comp.field.error-text.placement (FLD-7, FLD-31), size small (40), and in a right-to-left layout the value of an always left-to-right type beside its prefix (TXI-67). Lagging: this platform draws the text field as one view that draws its own frame, written against the token group comp.text-field, which the tokens do not have. It owes, first, its sources moved to the generated names of comp.input-box, comp.text-input and comp.field: they do not compile until then. Then the split: the text input as a view of its own, and the text field as the Field around it. Its names and its props stay. What it does today: React Native idiom (as TextInput): value / onChangeText, onEndEditing for a commit, onSubmitEditing for the action key; multiline, readOnly, maxLength and autoComplete keep TextInput's names. type maps to keyboardType, secureTextEntry, autoCapitalize, autoCorrect, inputMode and returnKeyType. A controlled value echoed back during a composition must not reset it (TXI-4). React Native gives JavaScript no signal that a composition is in progress, so the component cannot defer a write the product makes mid-composition; echoing the value back is safe. For date, time and date-time, onChangeText receives the value (ISO 8601 or empty), not the text as typed (TXI-29). The picker button is shown when onPickerRequest is given (undefined is picker false). Locale data needs Intl with formatToParts, which Hermes has only in part. Not built on this platform yet: the optional flag (optional) beside the required flag; the resize modes and the handle (TXI-37–TXI-41, TXI-69), the segmented date and time row (TXI-42–TXI-47) and the requirement label (FLD-4, FLD-5, TXI-50). The platform proposes its own idiom for the segments when it catches up — each unit focusable and adjustable on its own, with the same value and events. Not built on this platform yet: the words props have no defaults, and the product's words are read from the TanreiWordsProvider context. Not built on this platform yet, for type code: autoCorrect={false}, autoCapitalize="none", spellCheck={false}, autoComplete="off", smartInsertDelete={false}, keyboardType="ascii-capable" on iOS and "visible-password" on Android only where suggestions cannot be turned off otherwise, style={{ writingDirection: 'ltr', textAlign: 'left', fontFamily: … }}, the input row with direction: 'ltr'. TextInput has no multi-line form that does not wrap: wrap={false} needs a native text view, and until one exists the field wraps and its README says so. Not built on this platform yet: the count said as the product's sentence (counterText, counterNoLimitText, TXI-19); today the digits are said. Not built on this platform yet: comp.field.error-text.placement — the error text takes the help's place under every system, which is replace, the default; append, which keeps the help and draws the error text below it, is not drawn (FLD-7, FLD-31). Not built on this platform yet: size small (40), and in a right-to-left layout the value of an always left-to-right type beside its prefix (TXI-67).

トークン

トークン 参照先 解決値（ライト）
--tanrei-comp-field-counter-gap sys.space.space200 16px
--tanrei-comp-field-error-text-gap sys.space.space50 4px
--tanrei-comp-field-error-text-placement — 0
--tanrei-comp-field-label-icon-gap sys.space.space100 8px
--tanrei-comp-field-label-icon-size sys.icon.small 20px
--tanrei-comp-field-label-gap sys.space.space100 8px
--tanrei-comp-field-motion-state-duration sys.motion.role.state.default 250ms
--tanrei-comp-field-motion-state-easing sys.motion.easing.state cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-field-requirement-asterisk-gap sys.space.space25 2px
--tanrei-comp-field-requirement-gap sys.space.space100 8px
--tanrei-comp-field-requirement-mark sys.behavior.requirement-mark 0
--tanrei-comp-field-standard-counter-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-field-standard-disabled-counter-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-text-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-counter-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-label-icon-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-label-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-required-asterisk-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-supporting-text-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-value-text-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-label-icon-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-label-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-required-asterisk-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-supporting-text-color — #1b1b1b · 38%
--tanrei-comp-field-standard-disabled-value-text-color — #1b1b1b · 38%
--tanrei-comp-field-standard-error-text-color sys.color.error #cd262f
--tanrei-comp-field-standard-error-counter-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-field-standard-error-label-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-field-standard-error-label-color sys.color.on-surface #1b1b1b
--tanrei-comp-field-standard-error-required-asterisk-color sys.color.primary #1b1b1b
--tanrei-comp-field-standard-error-supporting-text-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-field-standard-error-value-text-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-field-standard-focused-counter-color — #4b4b4b
--tanrei-comp-field-standard-focused-error-text-color — #cd262f
--tanrei-comp-field-standard-focused-error-counter-color — #4b4b4b
--tanrei-comp-field-standard-focused-error-label-icon-color — #4b4b4b
--tanrei-comp-field-standard-focused-error-label-color — #1b1b1b
--tanrei-comp-field-standard-focused-error-required-asterisk-color — #1b1b1b
--tanrei-comp-field-standard-focused-error-supporting-text-color — #4b4b4b
--tanrei-comp-field-standard-focused-error-value-text-color — #4b4b4b
--tanrei-comp-field-standard-focused-label-icon-color — #4b4b4b
--tanrei-comp-field-standard-focused-label-color — #1b1b1b
--tanrei-comp-field-standard-focused-required-asterisk-color — #1b1b1b
--tanrei-comp-field-standard-focused-supporting-text-color — #4b4b4b
--tanrei-comp-field-standard-focused-value-text-color — #4b4b4b
--tanrei-comp-field-standard-label-icon-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-field-standard-label-color sys.color.on-surface #1b1b1b
--tanrei-comp-field-standard-required-asterisk-color sys.color.primary #1b1b1b
--tanrei-comp-field-standard-supporting-text-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-field-standard-value-text-color sys.color.on-surface-variant #4b4b4b
--tanrei-comp-field-supporting-text-gap sys.space.space50 4px
--tanrei-comp-field-value-text-gap sys.space.space200 16px
--tanrei-comp-field-label-typescale sys.typescale.label 500 14px/1.4286
--tanrei-comp-field-supporting-text-typescale sys.typescale.label-small 500 12px/1.3333
--tanrei-comp-field-value-text-typescale sys.typescale.label 500 14px/1.4286

フィクスチャ

基準となる描画パターンです。全プラットフォームが同じ ID でスナップショットを撮り、結果を比較できるようにしています。

variant: stacked (71)

stacked-empty

variant: stacked label: Email

stacked-filled

variant: stacked value: [email protected] label: Email

stacked-placeholder

variant: stacked label: Email placeholder: [email protected]

stacked-large

variant: stacked size: large value: [email protected] label: Email

stacked-small

variant: stacked size: small value: tokens label: Search

stacked-label-hidden

variant: stacked label: Search labelHidden: true placeholder: Search

stacked-supporting

variant: stacked value: [email protected] label: Email supportingText: We never share your address.

stacked-error

variant: stacked value: ada@ label: Email errorText: Enter a complete address. error: true

stacked-supporting-error

variant: stacked type: password value: ada1 label: Password supportingText: At least 8 characters, with one number. errorText: This password is too short. error: true

stacked-supporting-error-long

variant: stacked value: 12 Example Stret label: Billing address supportingText: Use the address your bank has on file, w… errorText: We could not find this address. Check th… error: true

stacked-supporting-error-rtl

variant: stacked type: password value: ada1 label: סיסמה supportingText: לפחות 8 תווים, כולל ספרה אחת. errorText: הסיסמה קצרה מדי. error: true direction: rtl

stacked-disabled

variant: stacked value: [email protected] label: Email disabled: true

stacked-read-only

variant: stacked value: [email protected] label: Email readOnly: true

stacked-icons

variant: stacked value: tanrei label: Search

stacked-label-icon

variant: stacked value: Ada Lovelace label: Display name slots: label-icon

stacked-affixes

variant: stacked type: number value: 120 label: Amount prefixText: $ suffixText: USD

stacked-counter

variant: stacked value: Ada Lovelace label: Display name maxLength: 40 counter: true

stacked-supporting-error-counter

variant: stacked value: Ada label: Display name supportingText: Shown beside your posts. errorText: This name is taken. Choose another. error: true maxLength: 40 counter: true

stacked-multiline

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3

stacked-password

variant: stacked type: password value: correct horse label: Password

stacked-date

variant: stacked type: date value: 2026-09-27 label: Start date locale: en-US

stacked-date-empty

variant: stacked type: date label: Start date locale: en-US segmentEmptyText: Empty

stacked-date-picker

variant: stacked type: date value: 2026-09-27 label: Start date locale: en-US picker: true pickerLabel: Choose date

stacked-date-picker-large

variant: stacked size: large type: date value: 2026-09-27 label: Start date locale: en-US picker: true pickerLabel: Choose date

stacked-date-ja

variant: stacked type: date value: 2026-09-27 label: 開始日 locale: ja-JP picker: true pickerLabel: 日付を選択

stacked-time-picker

variant: stacked type: time value: 14:30 label: Start time locale: en-US picker: true pickerLabel: Choose time

stacked-date-time-picker

variant: stacked type: date-time value: 2026-09-27T14:30 label: Starts locale: en-US picker: true pickerLabel: Choose date and time

stacked-date-error

variant: stacked type: date value: 2026-09-27 label: Start date errorText: Choose a date after today. error: true locale: en-US picker: true pickerLabel: Choose date

stacked-date-disabled

variant: stacked type: date value: 2026-09-27 label: Start date disabled: true locale: en-US picker: true pickerLabel: Choose date

stacked-multiline-auto-grown

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true

stacked-multiline-auto-grown-icons

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true

stacked-multiline-auto-max

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true maxRows: 3

stacked-multiline-manual

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3 resize: manual resizeLabel: Resize

stacked-multiline-manual-both

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3 resize: manual resizeAxis: both resizeLabel: Resize

stacked-multiline-manual-rtl

variant: stacked value: תודה על הסקירה. label: הודעה multiline: true minRows: 3 resize: manual resizeAxis: both resizeLabel: שינוי גודל direction: rtl

stacked-multiline-fixed

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3 resize: fixed

stacked-time-empty

variant: stacked type: time label: Start time locale: en-US segmentEmptyText: Empty

stacked-time-24h

variant: stacked type: time value: 14:30 label: 開始時刻 locale: ja-JP

stacked-date-rtl

variant: stacked type: date value: 2026-09-27 label: תאריך התחלה locale: he-IL picker: true pickerLabel: בחירת תאריך direction: rtl

stacked-required

variant: stacked label: Email required: true requiredText: Required

stacked-optional

variant: stacked label: Company optional: true optionalText: Optional

stacked-required-asterisk

variant: stacked label: Email required: true requiredMark: asterisk

stacked-required-ja

variant: stacked value: 山田 太郎 label: 氏名 required: true requiredText: 必須

stacked-optional-ja

variant: stacked label: 会社名 optional: true optionalText: 任意

stacked-required-label-icon

variant: stacked value: Ada Lovelace label: Display name required: true requiredText: Required slots: label-icon

stacked-required-error

variant: stacked label: Email errorText: Enter your email address. error: true required: true requiredText: Required

stacked-required-disabled

variant: stacked value: [email protected] label: Email disabled: true required: true requiredText: Required

stacked-required-rtl

variant: stacked label: אימייל required: true requiredText: חובה direction: rtl

stacked-code

variant: stacked type: code value: tanrei.comp.button.*.container.color label: Pattern

stacked-code-empty

variant: stacked type: code label: Pattern placeholder: tanrei.comp.*.color

stacked-code-large

variant: stacked size: large type: code value: tanrei.comp.button.*.container.color label: Pattern

stacked-code-affixes

variant: stacked type: code value: ^sys\.color\. label: Pattern supportingText: A regular expression, matched against a… prefixText: / suffixText: /u

stacked-code-multiline

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: Layer multiline: true minRows: 3

stacked-code-multiline-empty

variant: stacked type: code label: Layer placeholder: { "id": "acme", "extends": "tanrei" } multiline: true minRows: 3

stacked-code-multiline-wrap

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: Rule multiline: true

stacked-code-multiline-nowrap

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: Rule multiline: true minRows: 3 wrap: false

stacked-code-multiline-tabs

variant: stacked type: code value: build: pnpm generate pnpm check label: Recipe multiline: true

stacked-code-multiline-error

variant: stacked type: code value: { "id": "acme", } label: Layer errorText: Line 3: a name was expected before }. error: true multiline: true minRows: 3

stacked-code-multiline-counter

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: Layer multiline: true maxLength: 200 counter: true

stacked-code-multiline-manual

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: Rule multiline: true minRows: 3 resize: manual resizeAxis: both resizeLabel: Resize wrap: false

stacked-code-multiline-read-only

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: Rule readOnly: true multiline: true wrap: false

stacked-code-multiline-disabled

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: Layer disabled: true multiline: true

stacked-code-rtl

variant: stacked type: code value: tanrei.comp.button.*.container.color label: النمط supportingText: معرّف رمز، مع * لأي جزء. direction: rtl

stacked-code-empty-rtl

variant: stacked type: code label: النمط placeholder: tanrei.comp.*.color direction: rtl

stacked-code-affixes-rtl

variant: stacked type: code value: ^sys\.color\. label: النمط prefixText: / suffixText: /u direction: rtl

stacked-code-multiline-rtl

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: الطبقة supportingText: الصق ملف الطبقة هنا. required: true requiredText: مطلوب multiline: true minRows: 3 maxLength: 200 counter: true direction: rtl

stacked-code-multiline-empty-rtl

variant: stacked type: code label: الطبقة placeholder: { "id": "acme", "extends": "tanrei" } multiline: true minRows: 3 direction: rtl

stacked-code-multiline-brace-rtl

variant: stacked type: code value: { label: الطبقة multiline: true minRows: 3 direction: rtl

stacked-code-multiline-arabic-first-rtl

variant: stacked type: code value: ["مرحبا", "acme"] // تعليق: comment label: المصادر multiline: true minRows: 3 direction: rtl

stacked-code-multiline-nowrap-rtl

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: القاعدة errorText: السطر 2: القاعدة ينقصها سبب. error: true multiline: true minRows: 3 wrap: false direction: rtl

stacked-code-multiline-manual-rtl

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: الطبقة multiline: true minRows: 3 resize: manual resizeAxis: both resizeLabel: تغيير الحجم direction: rtl

variant: filled (7)

filled-empty

variant: filled label: Email

filled-filled

variant: filled value: [email protected] label: Email

filled-large

variant: filled size: large value: [email protected] label: Email

filled-error

variant: filled value: ada@ label: Email errorText: Enter a complete email address. error: true

filled-disabled

variant: filled value: [email protected] label: Email disabled: true

filled-multiline

variant: filled value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3

filled-code-multiline

variant: filled type: code value: { "id": "acme", "extends": "tanrei"… label: Layer multiline: true minRows: 3

variant: outlined (19)

outlined-empty

variant: outlined label: Email

outlined-filled

variant: outlined value: [email protected] label: Email

outlined-large

variant: outlined size: large value: [email protected] label: Email

outlined-label-hidden

variant: outlined type: search label: Search labelHidden: true placeholder: Search components

outlined-supporting

variant: outlined value: [email protected] label: Email supportingText: We only use it to sign you in.

outlined-error

variant: outlined value: ada@ label: Email errorText: Enter a complete email address. error: true

outlined-supporting-error

variant: outlined value: ada@ label: Email supportingText: We never share your address. errorText: Enter a complete email address. error: true

outlined-disabled

variant: outlined value: [email protected] label: Email disabled: true

outlined-read-only

variant: outlined value: [email protected] label: Email readOnly: true

outlined-icons

variant: outlined value: tanrei label: Search

outlined-affixes

variant: outlined type: number value: 120 label: Amount prefixText: $ suffixText: USD

outlined-counter

variant: outlined value: Ada Lovelace label: Display name maxLength: 40 counter: true

outlined-multiline

variant: outlined value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3

outlined-password

variant: outlined type: password value: correct horse label: Password

outlined-date-picker

variant: outlined type: date value: 2026-09-27 label: Start date locale: en-US picker: true pickerLabel: Choose date

outlined-multiline-manual

variant: outlined value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3 resize: manual resizeLabel: Resize

outlined-required

variant: outlined label: Email required: true requiredText: Required

outlined-optional

variant: outlined label: Company optional: true optionalText: Optional

outlined-code-multiline

variant: outlined type: code value: { "id": "acme", "extends": "tanrei"… label: Layer multiline: true minRows: 3

生成元 specs/text-field.spec.json, tokens/comp/field.tokens.json, design/tokens/

Web での描き方の違い

  • 要素のシャドウルートにあるのは、<tanrei-text-input> を入れた <tanrei-field> だけです。要素をインポートすると、2 つとも定義されます。
  • 要素は、置かれた場所の幅いっぱいに広がるブロックです。ブラウザーのテキスト入力欄と同じ幅のインラインのボックスではありません。
  • 要素はフォームに関連付けられます。name と form を受け取り、値を送信します（無効の間は何も送信しません）。リセットすると value 属性の値に戻り、ページの移動で復元され、無効な <fieldset> に従い、required が設定されていて値が空の間は、値がないことを報告します。2 つの構成要素がフォームに項目を加えることはありません。1 行のフィールドで Enter を押すと、要素のフォームの既定のボタンが押されます。action をキャンセルすると押されません。
  • input、change、action、pickerrequest、entryerror は、テキスト入力欄のイベントです。イベントのターゲットはこの要素で、どのリスナーでも event.target.value が新しい値です。detail の型は入力欄のもので、TanreiTextInputActionDetail、TanreiTextInputPickerRequestDetail、TanreiTextInputEntryErrorDetail です。
  • パーツ: field と text-input が 2 つの構成要素です。構成要素のパーツは、1 つ下の階層と同じ名前です。label-icon、supporting-text、counter と、container、outline、active-indicator、input、segment、prefix、suffix、leading-icon、trailing-icon、picker-button、resize-handle です。label と requirement-label は、どちらの構成要素が描いていても、描かれているほうを指します。field-label、text-input-label、field-requirement-label、text-input-requirement-label は、片方の構成要素のものを指します。
  • 要素そのものはフォーカスを受け取らず、ロールもありません。focus() は入力欄に移ります。ラベルの行、ボックス、浮き上がるラベルを押すと、入力欄にフォーカスが移ります。補足、エラーテキスト、文字数、行とボックスの間のすき間を押しても、何も起こりません。
  • 名前は label で付けます。ラベルを描かないときは label-hidden を併せて指定します。aria-label はここでは何にも名前を付けないので、使いません。
  • 属性は構成要素のものと同じです。supporting-text、error-text、min-rows、no-wrap などのケバブケースで、readonly、maxlength、autocomplete、min、max は HTML の名前のままです。required 属性はありません。required と書きます。
  • 要素が定義されるまでは、大きさがありません。高さを確保してください。

ガイドライン

使う場面

名前、メールアドレス、検索語、メッセージなど、利用者が値を打ち込むときに使います。決まった選択肢から選ぶ場合は、選ぶためのコントロールを使います。ラベルがほかの場所にあり、ボックスだけが必要なところ（ツールバーの絞り込み、テーブルのセルなど）では、テキスト入力欄を使います。

バリアントとサイズの選び方

1 つのフォームの中では、バリアントをそろえます。

バリアント 見た目 提供するシステム
Stacked（既定） 縁のない色付きのボックスの上にラベルを置きます。フォーカスするとボックスの縁の内側に線を引き、何も動かしません。エラーのときは、フォーカスしていなくても細い線を引きます。 すべてのシステム。Tanrei システムが提供するのはこれだけです。
Filled 色の付いたボックスと下線。ラベルは中で浮き上がります。 Material と cupertino のプリセット
Outlined 枠線。フォーカスすると太くなり、ラベルは枠線の上に浮き上がります。 Material と cupertino のプリセット

既定値はプリセットを含むすべてのシステムで stacked です。Material の浮き上がるラベルを使いたい Material のプロダクトは、フィールドの variant を outlined か filled に設定します。Tanrei システムでも filled と outlined は動作しますが、開発時に警告が出ます。

medium（40）は密度を上げたフィールド、large（56）は標準のフィールドです。絞り込みや密度の高い設定画面には medium、サインインや購入手続きのフォームには large が向いています。small（32）は小さなセレクトと同じ高さで、アプリバー、ツールバー、コントロールが密に並ぶ行に置くフィールドのためのものです。入力の文字は 14 になります。既定のシステムでは、ほかの 2 つのサイズでは入力の文字は 16 です。高さは最小値で、文字を大きくするとフィールドも大きくなり、当たり判定はいつも最小ターゲットを満たします。

ラベルとプレースホルダー

  • すべてのフィールドに label が必要です。Stacked ではボックスの上に先頭から置かれ、動いたり大きさが変わったりしません。長いラベルは切らずに折り返します。label-icon スロットで、ラベルの前にグリフを置けます。Filled と Outlined では、空で未フォーカスのあいだはフィールドの中に置かれ、フォーカスされるか値が入ると上に浮き上がります。
  • labelHidden はラベルを描かなくしますが、アクセシブルネームとしては残り、補足とエラーもボックスの下に残ります。ボックスだけが必要なところ（ツールバーの絞り込み、セル、ラベルを横に置いた行）では、代わりに、自身の label を持つテキスト入力欄を使います。
  • プレースホルダーは入力例などのヒントです。フィールドが空で、ラベルが入力の行にないときに表示されます。Stacked ではいつもそうで、ほかのバリアントではラベルが浮き上がっているか隠れているときだけです。名前にはなりません。

必須と任意

required と optional は、フォームがそのフィールドに何を求めるかを表します。required は答えが必要なこと、optional は空のままでもよいことです。フィールドが必須でも任意でもあることはありません。両方を設定すると必須になります。

  • 必須 は、フィールドを必須として伝え、ラベルの横に必須の印を描きます。
  • 任意 は、任意のタグを描き、その言葉をフィールドの説明に加えます。
  • 印 は、既定では Stacked のラベルのあとに置く小さなタグです。必須は Filled、任意は Tonal です。言葉は requiredText と optionalText で、プロダクトのものです。フィールドに書くか、setWords() でプロダクト全体に一度だけ渡します。Tanrei は言葉を同梱しません。requiredText がなければタグの位置にアスタリスクを描き、optionalText がなければタグを描きません。ラベルの行を高くすることはなく、ラベルの横に収まらないときは、次の行に折り返します。
  • アスタリスクにする。 必須のフィールドがどの印を描くかは、すべてのフォームに共通するデザインシステムの 1 つの選択 sys.behavior.requirement-mark で決まります。既定のシステムではタグ、Material のプリセットではアスタリスク、cupertino では何も描きません。requiredMark を使うと、フィールドごとに変えられます（tag、asterisk、または意味だけを残して何も描かない none）。Filled と Outlined のフィールドは、タグを求められてもアスタリスクを描きます。
  • 浮き上がるラベルでの任意。 Filled と Outlined のフィールドには、浮き上がるラベルの横に任意のタグを置く場所がありません。代わりに、ラベルのあとに optionalText を語として描き（「Company Optional」「会社名 （任意）」）、ラベルと一緒に置かれ、浮き上がります。語は、フォームで見せるとおりに、かっこ付きでもなしでも書きます。
  • 検証はしません。 値がないからといって、フィールドが error を設定することはありません。error と errorText は利用者側で設定します。

フォームの中で少ないほうに印を付けます。ほとんどが必須なら任意の項目に、その逆なら必須の項目に付けます。アスタリスクを使うなら（Filled と Outlined のフィールドは、必須のフィールドにいつも使います）、その意味をフォームの中、上のほうで一度書いておきます（「* 必須」）。アスタリスクは言葉ではなく慣習で、誰もが知っているわけではありません。

必須のフィールドには印が表示されます。印がいらない箇所では、requiredMark を none にします。

補足テキストとエラーテキスト

  • supportingText はフィールドの下に出す 1 行の補足で、フィールドの説明（description）としても読み上げられます。
  • 検証は利用者側で行います。値に問題があれば error を設定し、errorText を書きます。フィールドがエラーの間、エラーテキストは補足テキストの位置に代わって出るので、エラーのフォームが通常より高くなることはありません。補足に書いたことがまだ大事なら、エラーテキストでも伝えます。補足を見せ続けるデザインシステムは comp.field.error-text.placement を append にします。このときエラーテキストは補足の下に描かれ、エラーの間、フィールドは 1 行分高くなります（フィールドを参照）。
  • 間違っていることだけでなく、直し方を書きます。「無効です」ではなく「メールアドレスを最後まで入力してください。」です。
  • エラーは入力の途中ではなく、フィールドから離れたときか送信したときに出します。

カウンター

  • maxLength で入力できる文字数を制限します。数えるのは見た目の文字なので、絵文字や濁点付きの文字も 1 文字です。貼り付けた文字列は収まる長さに切り詰められます。プログラムから設定した値は切り詰めません。
  • counter を指定すると、補足の行の末尾に文字数を表示します。maxLength があれば上限も並べます（「12/40」）。
  • カウンターは、表示名や短い自己紹介のように、上限が利用者にとって意味を持つときだけ出します。

入力の種類

type でキーボード、自動修正、伏せ字入力が決まります。値はどの種類でも文字列です。

種類 キーボードと振る舞い
text 通常のキーボード。
email メールアドレス用のキーボード。自動大文字化と自動修正はしません。
password 伏せ字の安全な入力。自動修正はしません。常に 1 行です。
number 小数点付きの数字キーボード。値を数値に変換、丸め、検証することはありません。
search 通常のキーボードで、確定キーが「検索」になります。
tel 電話番号用のキーパッド。
url URL 用のキーボード。自動大文字化と自動修正はしません。
code 通常のキーボード。テキストには何も手を加えません。自動修正、自動大文字化、スペルチェック、文字の置き換えはしません。1 行、または multiline で複数行。コードを参照してください。
date、time、date-time 日付、時刻、またはその両方を、ロケールの数字の書き方で単位ごとに入力します。常に 1 行です。日付と時刻を参照してください。

autocomplete に HTML の自動入力名（email、current-password、one-time-code など）を指定すると、プラットフォームが自動入力できるようになります。各プラットフォームはそれを自分のコンテンツタイプに対応付けます。長さの決まった短いコードをマス目で描くのは、ワンタイムコード入力欄です。

複数行

multiline を付けると、改行を受け付け、複数の行を表示します。高さの決まり方は resize で選びます。

resize 高さ ハンドル minRows と maxRows
auto（既定） 行数に合わせて、短いモーションで変わります なし 最少と最多の行数です。最多を超えるとスクロールします。0 は上限なしです
manual 利用者が決めた高さです。minRows から始まります 末尾側の下の角 いちばん小さい高さと、いちばん大きい高さです
fixed minRows 行 なし maxRows は無視されます
  • Auto は、コメント、メッセージ、説明など、ほとんどのフィールドに向いています。長い文章でフォームの残りが押し出されては困る場所では、maxRows を設定します。
  • Manual は、メモ、長い説明、コードのように、利用者が読み返して整える文章に向いています。resizeAxis は既定で vertical です。both にすると、レイアウトが許す範囲で、フィールドの幅も変えられます。決めた大きさは保たれ、文章はその中で折り返してスクロールします。
  • Fixed は、住所の欄のように、レイアウトを動かしたくないフォームに向いています。
  • ハンドルはドラッグなしでも使えます。 末尾側の下の角にある小さいサイズのハンドルで、ポインターがフィールドの上に来るか、フィールドにフォーカスがあるまでは見えません。resizeLabel を名前とするフォーカスが止まる位置です。矢印キーで 1 行ずつ、Page Up と Page Down で minRows 行ずつ変わり、Home と End でいちばん小さい高さといちばん大きい高さになります。クリック、Enter、Space では、高さが文章に合い、すでに合っていれば minRows に戻ります。resizeAxis が both のときは、同じクリックでフィールドが置かれた場所いっぱいの幅になり、次のクリックで元の幅に戻ります。ポインターでも、ドラッグせずに幅を変えられます。線は小さくても、ターゲットは最小ターゲットです。人が大きさを変えると、フィールドは表示している行数（縦横に変えられるときは幅も）を添えて resizeend を発火します。その人が選んだ大きさを保存しておけます。無効なフィールドにはハンドルがありません。読み取り専用のフィールドは、読むために広さが必要なことがあるので、ハンドルを残します。
  • 文章より上は動きません。 複数行のフィールドの 1 行目は、1 行のフィールドが行を描く位置にあり、アイコン、接頭辞、接尾辞はその行の中央に揃います。2 行目以降はその下に続くので、高さが変わっても、ラベルと 1 行目はその場に留まります。

コード

type="code" は、人が読む文章ではなく機械が読むテキストのための種類です。パターン、識別子、キー、クエリ、JSON や YAML の断片などに使います。フィールドそのものは同じで、ラベル、補足、エラー、カウンター、サイズ、フォームでの振る舞いは変わりません。入力行だけが、コードを書かれたとおりに保持します。

  • どの言語でも左から右。 値、キャレット、プレースホルダー、接頭辞、接尾辞は、左から始まる 1 本の左から右の行です。右から左のページでも、コードの最初の文字が何であっても変わりません。空のフィールド、{ だけのフィールド、最初の文字列がアラビア語のフィールドは、同じように配置されます。それ以外はページに従います。ラベル、アイコン、補足テキストまたはエラーテキスト、カウンター、ハンドルです。右から左の文字で書かれた文字列やコメントは、その行の中で配置され、まわりの並びを変えません。
  • コード用の書体を、入力のサイズで。 書体はコードのロールのものです。サイズと行の高さは入力のままなので、コードのフィールドは隣のテキストフィールドと同じ高さになります。空白はすべて保たれ、タブ文字は次のタブ位置まで進み、2 つの文字が合字になることはありません。意味による色分けはしません。
  • 手を加えない。 値の修正、大文字化、スペルチェック、翻訳、補完をしないこと、まっすぐな引用符を曲がった引用符に変えないことを、プラットフォームに求めます。貼り付けはプレーンテキストで、1 文字ずつそのままです。値の前後を削ること、解析、検証はしません。正しい形かどうかは、利用者側が error と errorText で伝えます。
  • 1 行でも複数行でも。 パターンやキーには 1 行が向いています。multiline では、既定で、収まらない行が次の行に折り返します。値が持つ改行は、コード自身の改行だけです。
  • 折り返さない行。 wrap を false にすると（Web では no-wrap）、コードの 1 行が 1 行のまま描かれます。値の表、ログ、改行に意味があるファイルに向いています。長い行はフィールドの中で横にスクロールし、何の幅も広げません。wrap を読むのは複数行のコードのフィールドだけです。文章は常に折り返し、1 行のフィールドは常にその行の中でスクロールします。
  • Tab はフォーカスを移します。 キーの意味は変わりません。Tab で字下げはされず、Enter で字下げが足されることもなく、かっこが自動で閉じられることもありません。タブ文字は、貼り付けるかプロダクトが設定すれば入り、そのまま保たれます。
  • エディターではありません。 シンタックスの色分け、行番号、折りたたみ、行ごとのエラー表示はありません。入力せずに見せるコードにはコードブロックを使います。エディターが必要なら、プロダクトが選んだものを組み込みます。
  • プレースホルダーはコードの例で、コードとして描かれます。言葉で書くヒントは supportingText に入れます。フィールドが何を求めているか（「JSON」など）を伝えるのも、そこです。

右から左のフィールドでは、コードの値は左から始まります。一方、email、url、tel、number、password の値は、左から右に並んだうえで、フィールドの始端である右に寄ります。ほかのプラットフォームは、コードの種類をまだ実装していません。

日付と時刻

date、time、date-time のフィールドは、入力の行にセグメントを並べます。月、日、年、時、分と、12 時間制では午前・午後が、それぞれ 1 つのセグメントです。ロケールの順に、ロケールの区切りで並びます。フィールドは、値をタイムゾーンのない ISO 8601 の形で保持します。

種類 値 en-US での行 ja-JP での行
date 2026-09-27 09/27/2026 2026/09/27
time 14:30 2:30 PM 14:30
date-time 2026-09-27T14:30 09/27/2026, 2:30 PM 2026/09/27 14:30
  • ロケール。 locale、または各プラットフォームのロケールが、並び順、区切り、時計の方式、数字を決めます。空のセグメントはそれぞれのプレースホルダー（「mm」「dd」「yyyy」）を表示するので、行はいつも書き方を示します。各セグメントの幅は、プレースホルダーといちばん広い値のうち広いほうなので、入力しても消しても行は動きません。これらの種類では、placeholder、prefixText、suffixText、maxLength、multiline は無視されます。
  • 移動。 Tab は各セグメントを順に通り、そのあとピッカーボタンに進みます。左右の矢印キーは、どのレイアウト方向でも、その側のセグメントに移ります。数字で書く日付と同じく、行は左から右に書かれるからです。セグメントを押すと、そこにフォーカスが移ります。フォーカスのあるセグメントは選択したテキストとして描かれ、キャレットはありません。
  • 増減。 上下の矢印キーは、セグメントを 1 ずつ変え、端では反対の端に戻ります。空のセグメントでは、今日の日付か現在の時刻から始まります。Page Up と Page Down はもっと大きく動かし、Home と End は範囲の端に移します。
  • 数字を打つ。 数字を打つとセグメントが埋まり、それ以上桁が続かなくなったとき、または区切りの文字を打ったときに、フォーカスが次へ進みます。Backspace は 1 桁消し、空のセグメントでは前に戻ります。年は 4 桁必要です。存在しない日付は入力できません。月を選び直して日がその月の末日を超えると、その月の末日になります。
  • 貼り付け。 日付や時刻の全体をどのセグメントに貼り付けても、行全体が埋まります。ロケールの順に並んだ 3 つの数字のまとまりとして読み、最初のまとまりが 4 桁なら年として読むので、貼り付けた ISO の日付はどのロケールでも通ります。コピーと切り取りは、行全体を対象にします。
  • 値 は、すべてのセグメントが埋まり、その結果が選べる値になるまで空です。input は値が変わったとき、つまり最後のセグメントが埋まったとき、埋まった行を編集したとき、空にしたときに発火します。値が空のままになるセグメントの入力では発火しません。change は、値が変わった状態で、フォーカスがフィールドのセグメントとピッカーボタンから外れたとき、または確定キーを押したときに発火します。セグメントの間を移るだけでは、何も確定しません。
  • 入力エラー。 一部だけ埋まったまま離れると、フィールドは invalidText を表示します。min より前、max より後、または disabledDates にある値のまま離れると、unavailableText を表示します。どちらもエラーとして描かれ、理由（invalid か unavailable）を付けて entryError を発火します。次に編集するとこのエラーは消えます。フィールドが自分で設定する唯一のエラーで、利用者側の error プロパティには触れません。
  • プログラムから設定した値 は、そのまま表示し、検証せず、何も発火しません。

フィールドの時計の方式は、ロケールのものです。DateTimePicker と違って、12 時間制か 24 時間制かの設定も、分の刻みもありません。

ピッカーボタン。 picker を付けると、フィールドの末尾にアイコンだけのボタンを描きます。日付なら calendar_month、時刻なら schedule で、名前は pickerLabel です。押すと、値、種類、min、max を付けて pickerRequest を発火します。行が一部だけ埋まっているときは空の値を送り、入力エラーは出しません。このあとピッカーが値の全体を返すからです。フィールド自身は何も表示しません。プロダクト側で、対応するモードの DateTimePicker を開き（ドック型ならフィールドに固定し）、ピッカーの change からフィールドの value を設定します。ピッカーには、フィールドと同じ min、max、disabledDates を渡します。ピッカーが閉じると、フォーカスはボタンに戻ります。ボタンはフィールドと一緒に無効になり、読み取り専用のあいだは描かれません。

推奨

  • 通貨記号や単位など、値に含めない固定のテキストは prefixText と suffixText に入れます。
  • 入力を消す、パスワードを表示するといったアクションは、名前を付けた自前のアイコンだけのボタンとして末尾のスロットに置きます。フィールドに組み込まれているアクションはピッカーボタンだけで、利用者側のアクションのあとに並びます。
  • 数行にわたりうるテキストには multiline を使います。既定では minRows から maxRows まで伸び、それを超えるとスクロールします。
  • フォームが求めるフィールドには required を設定します。そのうえで、送信時に何が足りないかを errorText で伝えます。
  • 機械が読む値（パターン、キー、設定の断片）には type="code" を使い、何を書くべきかをラベルと supportingText で伝えます。

非推奨

  • プレースホルダーをラベルの代わりにしない。入力を始めた途端に消えてしまいます。
  • カード番号や郵便番号など、量ではない値に number を使わない。text と適切な autocomplete を使います。
  • 1 つのフォームでバリアントを混ぜない。
  • テキストフィールドをフィールドの中に入れない。すでにフィールドで、デバッグビルドがそのことを報告します。フィールドが囲むコントロールは、テキスト入力欄です。
  • 日付を text のフィールドと自前の解析で扱わない。date を使えば、ロケールの並び順、セグメントのキー操作、入力エラーが付いてきます。
  • required を設定したうえで、ラベルにも「（必須）」と書かない。印がすでに伝えており、スクリーンリーダーでは 2 度読まれます。
  • 手で大きさを変えるフィールドを、長い文章を見る唯一の手段にしない。開いた時点で役に立つだけの minRows を設定します。
  • 変えられない値を見せるためだけにフィールドを無効にしない。readOnly にすれば、フォーカス、選択、コピーはできます。
  • ::part(input) や自前のスタイルで、テキストフィールドに外からコード用の書体を当てない。要素に dir や spellcheck を足すこともしない。type="code" を使います。書体だけを変えたフィールドは、見た目は正しくても、入力された文字を修正してしまいます。
  • コードのフィールドをエディターとして使わない。長いコードを見せるために無効にもしない。無効なフィールドにはキャレットがなく、スクロールできません。readOnly にするか、コードブロックを使います。

アクセシビリティ

ロール
textbox
ラベル付け
The text field adds nothing to what its members expose, and the one thing it coordinates — the drawn count (TXF-67) — is kept from assistive technology, which hears the count from the input: the Field gives the text input its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the text input carries them on its own element (TXI-23). Assistive technology meets one text box — or, for a date or a time, one group of spin buttons — named by label, exactly as it meets a Field around a text input written by hand.
最小ターゲット
見た目のサイズが小さくても、ヒット領域は最小ターゲットサイズを満たします。 minimum 32px · pointer 44px · spacing 8px · touch 48px

キーボード操作

キー 動作
Every key The text input's (its accessibility block; TXI-3, TXI-41, TXI-43 to TXI-45, TXI-59). The text field handles no key and adds no focus stop (TXF-64).

備考

  • One level down is the same thing: a Field with a text input in it. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (TXF-62). What the pair by hand does not do by itself is keep the Field's count text equal to the input's count as the person types (TXF-67): the product writes it at each input.
  • On the web the two members stand in the text field's own shadow root, so the form meets the text field and not the input (TXF-63); focus passes through to the input (TXF-64).

生成元 specs/text-field.spec.json, tokens/sys/measure.tokens.json

コンポーネントが担うこと

  • 編集はプラットフォーム自身のテキスト要素で行うので、IME、音声入力、自動入力、選択、クリップボードは、そのプラットフォームのほかの入力欄と同じように動きます。日付と時刻は明示された例外で、セグメントの行はフィールド自身のものです。
  • 日付や時刻のフィールドは、ラベルを名前とするグループです。各セグメントは、単位とラベルを名前とするスピンボタンで（「month, Start date」）、範囲と値を伝えます。空のセグメントは segmentEmptyText を読み上げます。
  • 必須のフィールドは、必須として伝えます。印そのものは支援技術から隠すので、2 度読まれることはありません。任意の言葉は、フィールドの説明と一緒に読み上げられます。
  • サイズ変更のハンドルは、resizeLabel を名前とするフォーカスが止まる位置で、行数を値とするセパレーターとして伝えます。矢印キー、Home、End で大きさを変えられるので、ドラッグに頼る操作はありません。ヒット領域は最小ターゲットを満たします。
  • ラベルは、描かれていても隠されていても、アクセシブルネームになります。プレースホルダーが名前になることはありません。
  • 表示中の補足テキストまたはエラーテキストと、文字数が、フィールドの説明になります。表示中の接頭辞と接尾辞も説明に含まれるので、単位や通貨は値と一緒に読み上げられます。
  • 無効状態を伝えます。invalid、必須、読み取り専用の状態も、プラットフォームにあれば伝えます。日付や時刻のフィールドの入力エラーは、error とまったく同じように伝えます。
  • ピッカーボタンは pickerLabel を名前とするボタンで、ダイアログを開くことを伝え、タブ順では最後のセグメントのあとに来ます。
  • フォーカス中にエラーが現れるか変わると、1 度だけ控えめに読み上げます。文字数は、入力が 1 秒止まったときに表示どおり（「12/40」）1 度だけ読み上げ、キーを打つたびには読みません。
  • 検索フィールドは、プラットフォームに検索ボックスのロールがあれば、そのロールで伝えます。
  • コードのフィールドは、ほかの種類と同じテキストボックスで、multiline なら複数行のテキストボックスです。コードを保持していることを伝えるロール、ロールの説明、言葉はなく、値のどの部分もスペルの誤りとして示されません。Tab では必ずフィールドを離れます。行を折り返さない場合は、キャレットの移動でスクロールし、フォーカスはスクロールしないコンテナに示されます。
  • フォーカスは、キーボードでもポインターでも、フィールド自身の縁で示します。Stacked ではボックスの内側の線、Filled と Outlined では太く色の付いた縁です。ヒット領域は最小ターゲットを満たします。
  • ラベルかボックスを押すと、フォーカスが入力欄に移ります。何かが操作されることはありません。補足、エラーテキスト、文字数を押しても、何も起こりません。
  • 名前、説明、状態は、フィールドが囲んだコントロールに結び付けるのとまったく同じように結び付けられます。1 つ下の階層で自分で書いたフィールドも、同じテキストボックスになります。
  • ラベルがない場合は、デバッグビルドで報告します。

プラットフォームごとの既知の制約：

  • SwiftUI、Compose、Flutter、React Native は、印を描かない required フラグのままで、リサイズの方式とハンドル、セグメントはありません。
  • Web：月や分に最初の数字が入ると、セグメントの行が数ピクセルずれます。ロケールの最後のセグメントが 2 桁の場合、input が 2 回発火することがあります。Android の画面上のキーボードでは、空のセグメントで Backspace を押しても前に戻れません。狭いフィールドより幅の広い行は、スクロールせずにはみ出します。
  • 一部だけ埋まった日付の行は、すでに空文字列である value に空文字列を設定しても、空にできません。
  • Web：フォーカススタイルが glow のとき、Filled のフィールドの光彩は、角のない下側の角まで丸くなります。
  • Web：IME の変換と、自動入力されたときのラベルは、Chromium でしかテストしていません。
  • Web：行を折り返さない読み取り専用のコードのフィールドは、ブラウザーが編集しないテキストをスクロールするのと同じキーでスクロールします。Firefox ではキャレットで、Chrome では矢印キーで、Safari では Option と矢印キーです。Firefox では、ページの向きが変わると、このフィールドのスクロール位置が左端に戻ります。
  • SwiftUI、Compose、Flutter、React Native は、コードの種類をまだ実装していません。これらでは type に code がなく、フィールドに wrap もありません。
  • SwiftUI には invalid、必須、読み取り専用の状態がありません。これらは描画や動作には反映されますが、読み上げられません。エラーは説明に含まれるテキストとしてしか伝わりません。
  • SwiftUI は IME の変換中の状態を知ることができません。そのため maxLength は変換中の文字にも適用され、変換中にプログラムから変えた値も確定まで待たずに適用されます。
  • SwiftUI：選択したテキストのハイライトは、フィールドの選択色ではなく、キャレットの色合いになります。
  • SwiftUI は、読み取り専用のフィールドの値を、テキストフィールドではなく選択できるテキストとして描きます。
  • SwiftUI が .labelsHidden() を読めるのは iOS 18 と macOS 15 からです。それより前のバージョンでは、ラベルは描かれたままです。
  • React Native は IME の変換中の状態を知ることができません。変換中にプログラムから変えた値や maxLength による制限はすぐに適用され、変換が途中で確定してしまうことがあります。
  • React Native には invalid、必須、読み取り専用の状態がありません。エラーは説明に含まれるテキストとしてしか伝わらず、必須と読み取り専用は読み上げられません。
  • React Native：読み上げ、自動入力、種類ごとのキーボードはモックでしか試しておらず、実機ではまだ確かめていません。
  • iOS の React Native では、キャレットと選択範囲のハイライトの色合いが 1 つしかありません。フィールドはキャレットの色を優先するので、ハイライトはフィールドの選択色ではなく、キャレットの色を薄めたものになります。
  • React Native：Filled のフィールドの光彩は上側の角にしか沿わず、プレースホルダーとキャレットの色は、状態のモーションに沿って変わらずに一度に切り替わります。
  • Flutter は検索フィールドを、検索ボックスのロールではなく、検索用の入力種別として伝えます。
  • Flutter は Android などのタッチ画面で、選択ハンドルと選択ツールバーを描きません。長押しとキーボードショートカットでの選択とコピーはでき、iOS ではシステムのメニューが出ます。
  • Flutter：先頭のスロットに置いた操作できる要素は、フォーカス順で入力欄の後ではなく前に来ます。
  • Compose には必須の状態がないため、代わりに状態の説明として「Required」を読み上げます。
  • Compose：maxLength と文字数は見た目どおりの文字単位で数えますが、絵文字の連結や国旗はテストしていません。テストは Robolectric 上の JVM で動き、その文字の規則がこれらを知らないためです。
  • Compose：TalkBack によるエラーと文字数の読み上げ、実際の IME、実際の自動入力サービスは、実機ではまだ試していません。

利用者側で行うこと

  • 値の内容を表すラベルを書き、隠す場合も必ず設定します。
  • 直し方が分かるエラーテキストを書き、error は利用者側で設定します。SwiftUI と React Native では、そのテキストがエラーを耳で知る唯一の手段です。日付や時刻のフィールドでは、invalidText と unavailableText も書き、segmentEmptyText を渡します。これがなければ、空のセグメントは値なしとして読み上げられます。
  • ピッカーボタンの pickerLabel をプロダクトの言語で設定し、pickerRequest を受けてピッカーを開きます。
  • required を設定し、requiredText と optionalText を渡します。フィールドに書くか、setWords({ requiredText, optionalText }) でプロダクト全体に一度だけ渡します。resizeLabel と segmentEmptyText も同じように渡せます。Web では Tanrei は言葉を同梱しません。足りない言葉は開発時に報告されます。プロダクトの言葉を参照してください。SwiftUI、Compose、Flutter、React Native が追従するまで、これらのフィールドは印を描かず、SwiftUI と React Native は必須の状態を読み上げません。これらのプラットフォームでは、必須であることをラベルに書きます。
  • サイズ変更のハンドルに、resizeLabel で名前を付けます。これがなくてもハンドルは描かれて動作しますが、名前を持ちません。
  • 単位や通貨は値に含めず、prefixText か suffixText に入れます。そうすれば入力する必要がなく、値と一緒に読み上げられます。
  • コードのフィールドでは、何を書くべきかを label と supportingText で伝え（「Webhook の本文」「JSON」）、何が誤っているかを errorText で伝えます。フィールドはその言語を知りません。
  • 末尾のアイコンボタンには、プロダクトの言語で名前を付けます。
  • Compose では「Invalid」と「Required」という言葉がライブラリの文字列リソース（tanrei_invalid、tanrei_required）から来ます。翻訳するには、アプリのリソースで上書きします。
  • Web では、iOS Safari が 16 px より小さい文字の入力欄に入るとページを拡大します。既定のシステムのフィールドは、どちらのサイズでも 16 px の文字を使います。レイヤでそれより小さくすると、拡大がまた起こります。

ソースコードと Issue（GitHub）