# TextInput

A text field with optional prefix, suffix, and clear button.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/TextInput.tsx)

Figma: [Inputs/Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3846) (`TextInput.Group`), [Inputs/Search Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-2265) (`TextInput.Group`), [Inputs/Text Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-1285) (`TextInput.Group`), [Search](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3365) (`TextInput.Group`), [Text Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3316) (`TextInput.Group`)

## Overview

An input is a filled text field composed from a group, an optional prefix and suffix, a control, and a clear button.

## Examples

### Basic

```tsx
import { Field, style, TextInput } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>To</Field.Label>
      <TextInput.Group>
        <TextInput.Control autoComplete="email" placeholder="Address, email or contact" />
      </TextInput.Group>
      <Field.Description>Paste an address or pick a contact</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Basic.tsx)

### Icons

Put an icon that gives the field its meaning, such as `Search` or `Mail`, in `TextInput.Prefix`. Put an icon for an action on the field, such as paste, in `TextInput.Suffix`.

```tsx
import { Field, style, TextInput } from '@tempoxyz/ds'
import { Clipboard, Search } from '@tempoxyz/ds/icons'

export const fill = true
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Recipient</Field.Label>
      <TextInput.Group>
        <TextInput.Prefix>
          <Search />
        </TextInput.Prefix>
        <TextInput.Control defaultValue="maya@studio.co" />
        <TextInput.Suffix>
          <Clipboard />
        </TextInput.Suffix>
      </TextInput.Group>
      <Field.Description>Paste an address or pick a contact</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Icons.tsx)

### Search

Add a `Search` icon in `TextInput.Prefix` and a `TextInput.Clear`. The clear button shows once the field has a value, and Escape empties the field before it closes an enclosing [Dialog](/docs/components/dialog).

```tsx
import { Field, style, TextInput } from '@tempoxyz/ds'
import { Search } from '@tempoxyz/ds/icons'

export const fill = true
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <TextInput.Group>
        <TextInput.Prefix>
          <Search />
        </TextInput.Prefix>
        <TextInput.Control
          aria-label="Search contacts"
          defaultValue="Maya"
          placeholder="Name, email or address"
          type="search"
        />
        <TextInput.Clear />
      </TextInput.Group>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Search.tsx)

### Variant

Set `variant` on `TextInput.Group` to `default` (default) or `outlined`, which draws a 1px line instead of the fill.

```tsx
import { Field, style, TextInput } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.grid()}>
      {(['default', 'outlined'] as const).map((variant) => (
        <Field.Root key={variant}>
          <Field.Label>To</Field.Label>
          <TextInput.Group variant={variant}>
            <TextInput.Control placeholder="Address, email or contact" />
          </TextInput.Group>
          <Field.Description>Paste an address or pick a contact</Field.Description>
        </Field.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Variant.tsx)

### Size

Set `size` on `TextInput.Group` to `medium` (default) or `large`, a 52px search bar with 20px icons and larger corners.

```tsx
import { Field, style, TextInput } from '@tempoxyz/ds'
import { Search } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <div {...styles.grid()}>
      {(['medium', 'large'] as const).map((size) => (
        <Field.Root key={size}>
          <TextInput.Group size={size}>
            <TextInput.Prefix>
              <Search />
            </TextInput.Prefix>
            <TextInput.Control
              aria-label="Search tokens"
              placeholder="Search tokens"
              type="search"
            />
            <TextInput.Clear />
          </TextInput.Group>
        </Field.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Size.tsx)

### Appearance

Set `appearance` on `TextInput.Group` to `base` (default) or `overlay`, which draws a translucent fill and white text over an image or video.

```tsx
import { Field, style, TextInput } from '@tempoxyz/ds'
import { Search } from '@tempoxyz/ds/icons'

export const fill = true
export function Demo() {
  return (
    <div {...styles.backdrop()}>
      <Field.Root {...styles.field()}>
        <TextInput.Group appearance="overlay" size="large">
          <TextInput.Prefix>
            <Search />
          </TextInput.Prefix>
          <TextInput.Control aria-label="Search places" placeholder="Search places" type="search" />
          <TextInput.Clear />
        </TextInput.Group>
      </Field.Root>
    </div>
  )
}

namespace styles {
  // A dark gradient stands in for the image or video under an overlay field.
  export const backdrop = style({
    backgroundImage: 'linear-gradient(135deg, #3d3d3d, #141414) !custom',
    borderRadius: 'sm',
    padding: '32',
  })

  export const field = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Appearance.tsx)

### Invalid

Set `invalid` or `success` on `TextInput.Group`, or inherit either from `Field.Root`. A state set after mount plays a one-shot nudge or pop.

```tsx
import { Field, style, TextInput } from '@tempoxyz/ds'
import { useState } from 'react'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Send />
      <Field.Root
        validate={(value) => (String(value).includes('@') ? null : 'Enter a valid email.')}
        validationMode="onChange"
      >
        <Field.Label>Email</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="alice@example.com" type="email" />
        </TextInput.Group>
        <Field.Description>Remove the @ to swap in the error.</Field.Description>
        <Field.Error />
      </Field.Root>
      <Field.Root invalid>
        <Field.Label>Email</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="alice" type="email" />
        </TextInput.Group>
        <Field.Description>Used for receipts.</Field.Description>
        <Field.Error match>Enter a valid email.</Field.Error>
      </Field.Root>
    </div>
  )
}

function Send() {
  const [amount, setAmount] = useState('')
  const invalid = Number(amount) > 1240.5

  return (
    <Field.Root invalid={invalid} success={amount !== '' && !invalid}>
      <Field.Label>You send</Field.Label>
      <TextInput.Group>
        <TextInput.Prefix>$</TextInput.Prefix>
        <TextInput.Control inputMode="decimal" onValueChange={setAmount} placeholder="0.00" />
        <TextInput.Suffix>USDC</TextInput.Suffix>
      </TextInput.Group>
      <Field.Description>Balance 1,240.50 USDC</Field.Description>
      <Field.Error match={invalid}>Exceeds your balance.</Field.Error>
    </Field.Root>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Invalid.tsx)

### Disabled

Disable a field only when the app sets the value, and say why in the `Field.Description`.

```tsx
import { Field, style, TextInput } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Field.Root disabled {...styles.field()}>
      <Field.Label>Network</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="Tempo" />
      </TextInput.Group>
      <Field.Description>Set by the app you are paying</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TextInput/Disabled.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { TextInput } from '@tempoxyz/ds'

<TextInput.Group>
  <TextInput.Prefix />
  <TextInput.Control />
  <TextInput.Suffix />
  <TextInput.Clear />
</TextInput.Group>
```

## Guidelines

### When to Use

* Collect one line of text, such as an email or a 0x address.
* Search a list or table, with a `Search` icon in `TextInput.Prefix` and a `TextInput.Clear`.

### When Not to Use

* Use [AmountInput](/docs/components/amount-input) for token and fiat amounts. It rejects non-decimals and adds a Max action.
* Use [NumberField](/docs/components/number-field) for quantities that step up and down.
* Use [Textarea](/docs/components/textarea) for text over one line.
* Use [OtpField](/docs/components/otp-field) for one-time passcodes.
* Use [Select](/docs/components/select) or [Combobox](/docs/components/combobox) if the value must come from a list, and [Autocomplete](/docs/components/autocomplete) if a list only suggests values.

### Always Show a Label

A placeholder disappears on the first keystroke. Use it only for a format example, such as `0x…`. Leave out the visible label only when the dialog title already names the field, such as a search field, and set `aria-label`.

**Do:** Name the field in a `Field.Label` and keep the placeholder as a format hint.

```tsx
/**
 * Do example for "Always Show a Label" on the TextInput page.
 * Name the field in a `Field.Label` and keep the placeholder as a format hint.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Recipient address</Field.Label>
      <TextInput.Group>
        <TextInput.Control placeholder="0x…" />
      </TextInput.Group>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

**Don't:** Use the placeholder as the only label.

```tsx
/**
 * Don't example for "Always Show a Label" on the TextInput page.
 * Don't use the placeholder as the only label.
 * @module
 */
import { style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <TextInput.Group {...styles.field()}>
      <TextInput.Control aria-label="Recipient address" placeholder="Recipient address" />
    </TextInput.Group>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

### Size the Field to Its Value

`TextInput.Group` fills its container. If the value is short, narrow it with `style` or `className`.

**Do:** Give a short value a short field, and a long value the full column.

```tsx
/**
 * Do example for "Size the Field to Its Value" on the TextInput page.
 * Give a short value a short field, and a long value the full column.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.form()}>
      <Field.Root>
        <Field.Label>TokenLogo symbol</Field.Label>
        <TextInput.Group {...styles.short()}>
          <TextInput.Control defaultValue="USDC" />
        </TextInput.Group>
      </Field.Root>
      <Field.Root>
        <Field.Label>Webhook URL</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="https://api.example.com/hooks" type="url" />
        </TextInput.Group>
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const form = style({
    display: 'grid',
    gap: '16',
    maxWidth: '18rem !custom',
    width: '100% !custom',
  })

  export const short = style({ width: '7rem !custom' })
}
```

**Don't:** Stretch a four-character symbol across the column or squeeze a URL into a small box.

```tsx
/**
 * Don't example for "Size the Field to Its Value" on the TextInput page.
 * Don't stretch a four-character symbol across the column or squeeze a URL into a small box.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.form()}>
      <Field.Root>
        <Field.Label>TokenLogo symbol</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="USDC" />
        </TextInput.Group>
      </Field.Root>
      <Field.Root>
        <Field.Label>Webhook URL</Field.Label>
        <TextInput.Group {...styles.short()}>
          <TextInput.Control defaultValue="https://api.example.com/hooks" type="url" />
        </TextInput.Group>
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const form = style({
    display: 'grid',
    gap: '16',
    maxWidth: '18rem !custom',
    width: '100% !custom',
  })

  export const short = style({ width: '7rem !custom' })
}
```

### Use Prefixes and Suffixes for Fixed Context

Put a currency symbol, protocol, or search icon in `TextInput.Prefix`, and a unit such as `USDC` in `TextInput.Suffix`.

**Do:** Show the unit in `TextInput.Suffix` so people type only the number.

```tsx
/**
 * Do example for "Use Prefixes and Suffixes for Fixed Context" on the TextInput page.
 * Show the unit in `TextInput.Suffix` so people type only the number.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Slippage tolerance</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="0.5" inputMode="decimal" />
        <TextInput.Suffix>%</TextInput.Suffix>
      </TextInput.Group>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '9rem !custom' })
}
```

**Don't:** Make people type the unit into the value.

```tsx
/**
 * Don't example for "Use Prefixes and Suffixes for Fixed Context" on the TextInput page.
 * Don't make people type the unit into the value.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Slippage tolerance</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="0.5%" />
      </TextInput.Group>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '9rem !custom' })
}
```

* **Content:** Keep prefixes and suffixes to a symbol, icon, or one short word. Put other buttons beside the group, not in a suffix.
* **Icons:** Use a leading icon for meaning, such as `Search`, and a trailing icon for an action on the field, such as paste or scan.
* **Clear:** `TextInput.Clear` appears only inside a `Field.Root` once the control has a value. Add it to search fields and filters, not to one-time forms.

### Help Browsers and Keyboards Fill the Field

Set `type`, `inputMode`, and `autoComplete` on `TextInput.Control` to select the on-screen keyboard and enable saved values.

* **Email (email):** Set `type="email"` and `autoComplete="email"`.
* **Name (name):** Set `autoComplete="name"`.
* **URL or Webhook (url):** Set `type="url"` and `autoComplete="url"`.
* **Search (search):** Set `type="search"`.
* **0x Address (off):** Turn off autofill, capitalizing, and spellcheck.
* **Numeric Code (numeric):** Set `inputMode="numeric"` and turn off autofill.

Avoid `type="number"` for amounts and identifiers. It drops leading zeros, accepts `e`, and some browsers change the value on scroll.

For labels, descriptions, errors, and validation timing, see [Field](/docs/components/field).

## Accessibility

An input renders a native `<input>` inside a styled group. Inside a `Field.Root`, it links to the label, description, and error. See [Accessibility](/docs/foundations/accessibility) for the baseline.

### Semantics

* **TextInput.Control (textbox):** A native input whose role follows its type.
* **TextInput.Group (div):** Has no role of its own.
* **Invalid and Success (aria-invalid):** `invalid` sets `aria-invalid`. `success` sets no ARIA state.
* **TextInput.Prefix and TextInput.Suffix:** Plain text, such as "$" or "USDC". Not part of the input's name.
* **TextInput.Clear (button):** Labelled "Clear". Its hit area extends past its circle.

### Keyboard

* **Move to the TextInput (Tab):** Moves focus to the input, then to the clear button when shown.
* **Clear the TextInput (Enter or Space):** On the clear button, empties the input and returns focus to it.
* **Clear Before Closing (Escape):** With a clear button, Escape empties a filled input first.

All other keys follow the native input.

### Size and Motion

* **Target Size (48px):** Every field is 48px tall, above the 24px WCAG 2.2 minimum.
* **Reduced Motion (reduce):** Under reduced motion, the nudge and pop don't play.

### Your Responsibilities

* **Label Every TextInput (Field.Label):** Use a visible label, or an `aria-label` when none fits. A prefix icon doesn't name it.
* **Name the Unit:** If the unit matters, put it in the label or description, such as "Amount in USDC".
* **Declare the Purpose (autoComplete):** Set it with `type` and `inputMode` to declare the field's purpose. WCAG requires it for personal data.
* **Explain Invalid Values (Field.Error):** Don't rely on the red fill alone. Explain an invalid value in text, such as "Enter an amount above 0".

## Related

[Field](/docs/components/field)

Use for labels, descriptions, and errors.

[AmountInput](/docs/components/amount-input)

Use for token and fiat amounts.

[Textarea](/docs/components/textarea)

Use for multi-line text.

[Combobox](/docs/components/combobox)

Use for picking from a long list by typing.

[Forms](/docs/patterns/forms)

Covers laying out fields and actions.

[Errors and Validation](/docs/patterns/errors-and-validation)

Covers when and where to show errors.
