# Input

A text input component for forms and user data entry with built-in styling and accessibility features.

Source: https://webjs.dev/ui/docs/components/input

```ts
import { html } from '@webjsdev/core';
import { fieldClass, fieldLabelClass, fieldDescriptionClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputDemo() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
      <label data-slot="field-label" for="input-demo-api-key" class=${fieldLabelClass()}>API Key</label>
      <input data-slot="input" id="input-demo-api-key" type="password" placeholder="sk-..." aria-describedby="input-demo-api-key-description" class=${inputClass()}>
      <p data-slot="field-description" id="input-demo-api-key-description" class=${fieldDescriptionClass()}>
        Your API key is encrypted and stored securely.
      </p>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add input
```

### Copy and paste the following code into your project.

````ts title="components/ui/input.ts"
/**
 * Input: styled native `<input>`. Tier-1 class helper. Works with every
 * input type (text, email, password, number, search, tel, url, date,
 * time, file, color, …). Form submission, autocomplete, browser
 * validation, and password managers all work because it IS the native
 * input.
 *
 * shadcn parity:
 *   Input  → inputClass()
 *
 * Pair with `<label class=${labelClass()} for="...">` and a hint paragraph
 * (`<p class=${hintClass()} id="...-hint">`). Wrap all three in
 * `<div class=${fieldClass()}>` for the canonical field rhythm.
 *
 * Design tokens used: --input, --background, --primary, --primary-foreground,
 * --muted-foreground, --foreground, --ring, --destructive.
 *
 * A11y (required for accessible output):
 *   LABEL IT. A `<label class=${labelClass()} for="<the input's id">` is the
 *   whole requirement, and the `for` / `id` pair is what links them. Without it
 *   the input has no accessible name and a screen reader announces only "edit
 *   text". A `placeholder` is NOT a label: it disappears the moment the user
 *   types, and some engines never expose it as a name at all.
 *   Every `aria-describedby` must point at an element that EXISTS on the page.
 *   A dangling id silently contributes nothing, so the hint or error text is
 *   never announced; the example below therefore renders the `#email-hint` node
 *   it references rather than assuming it.
 *   On a validation failure set `aria-invalid="true"` (the class styles the
 *   error ring off it) and point `aria-describedby` at the error text, so the
 *   reason is announced along with the field rather than only shown in red.
 *   Set the right `type` and `autocomplete`. Both are accessibility features:
 *   `type` picks the mobile keyboard and the native validation, and
 *   `autocomplete` is what lets a password manager or an autofill user avoid
 *   retyping. `type="search"` / `type="email"` also announce as such.
 *   A required field wants the native `required` attribute, not just an
 *   asterisk in the label, so the state reaches assistive tech.
 *
 * @example
 * ```html
 * <div class=${fieldClass()}>
 *   <label class=${labelClass()} for="email">Email</label>
 *   <input class=${inputClass()} type="email" name="email" id="email" required
 *          autocomplete="email" aria-describedby="email-hint">
 *   <p class=${hintClass()} id="email-hint">We never share it.</p>
 * </div>
 *
 * <!-- Failed validation: invalid state plus the reason, both announced. -->
 * <div class=${fieldClass()}>
 *   <label class=${labelClass()} for="email-2">Email</label>
 *   <input class=${inputClass()} type="email" name="email" id="email-2"
 *          aria-invalid="true" aria-describedby="email-2-error" value="nope">
 *   <p class=${errorClass()} id="email-2-error">Enter a valid email address.</p>
 * </div>
 * ```
 */
import { cn } from '../lib/utils.ts';

const INPUT_BASE =
  'h-9 rounded-md border border-input bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] selection:bg-primary selection:text-primary-foreground file:h-7 file:text-sm file:font-medium md:text-sm dark:bg-input/30 w-full min-w-0 outline-none file:inline-flex file:border-0 file:bg-transparent file:text-foreground placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50';

const INPUT_FOCUS =
  'focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50';

const INPUT_INVALID =
  'aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40';

/** Compose Tailwind classes for a native `<input>`. */
export function inputClass(): string {
  return cn(INPUT_BASE, INPUT_FOCUS, INPUT_INVALID);
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import { inputClass } from '#components/ui/input.ts';
```

```ts
<input data-slot="input" class=${inputClass()}>
```

## Basic

```ts
import { html } from '@webjsdev/core';
import { inputClass } from '#components/ui/input.ts';

export default function InputBasic() {
  return html`<input data-slot="input" placeholder="Enter text" aria-label="Text" class=${inputClass()}>`;
}
```

## Field

Use `fieldClass()`, `fieldLabelClass()`, and `fieldDescriptionClass()` to create an input with a label and description.

```ts
import { html } from '@webjsdev/core';
import { fieldClass, fieldLabelClass, fieldDescriptionClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputField() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
      <label data-slot="field-label" for="input-field-username" class=${fieldLabelClass()}>Username</label>
      <input data-slot="input" id="input-field-username" type="text" placeholder="Enter your username" class=${inputClass()}>
      <p data-slot="field-description" class=${fieldDescriptionClass()}>
        Choose a unique username for your account.
      </p>
    </div>
  `;
}
```

## Field Group

Use `fieldGroupClass()` to show multiple fields and to build forms.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import {
  fieldGroupClass, fieldClass, fieldLabelClass, fieldDescriptionClass,
} from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputFieldgroup() {
  return html`
    <div data-slot="field-group" class=${fieldGroupClass()}>
      <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
        <label data-slot="field-label" for="fieldgroup-name" class=${fieldLabelClass()}>Name</label>
        <input data-slot="input" id="fieldgroup-name" placeholder="Jordan Lee" class=${inputClass()}>
      </div>
      <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
        <label data-slot="field-label" for="fieldgroup-email" class=${fieldLabelClass()}>Email</label>
        <input data-slot="input" id="fieldgroup-email" type="email" placeholder="name@example.com" class=${inputClass()}>
        <p data-slot="field-description" class=${fieldDescriptionClass()}>
          We&apos;ll send updates to this address.
        </p>
      </div>
      <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
        <button type="reset" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>
          Reset
        </button>
        <button type="submit" data-slot="button" data-variant="default" data-size="default" class=${buttonClass()}>Submit</button>
      </div>
    </div>
  `;
}
```

## Disabled

Use the `disabled` attribute to disable the input. To style the disabled state, add `data-disabled="true"` to the field.

```ts
import { html } from '@webjsdev/core';
import { fieldClass, fieldLabelClass, fieldDescriptionClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputDisabled() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" data-disabled="true" class=${fieldClass()}>
      <label data-slot="field-label" for="input-demo-disabled" class=${fieldLabelClass()}>Email</label>
      <input data-slot="input" id="input-demo-disabled" type="email" placeholder="Email" disabled class=${inputClass()}>
      <p data-slot="field-description" class=${fieldDescriptionClass()}>This field is currently disabled.</p>
    </div>
  `;
}
```

## Invalid

Use the `aria-invalid="true"` attribute to mark the input as invalid. To style the invalid state, add `data-invalid="true"` to the field.

```ts
import { html } from '@webjsdev/core';
import { fieldClass, fieldLabelClass, fieldDescriptionClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputInvalid() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" data-invalid="true" class=${fieldClass()}>
      <label data-slot="field-label" for="input-invalid" class=${fieldLabelClass()}>Invalid Input</label>
      <input data-slot="input" id="input-invalid" placeholder="Error" aria-invalid="true" class=${inputClass()}>
      <p data-slot="field-description" class=${fieldDescriptionClass()}>
        This field contains validation errors.
      </p>
    </div>
  `;
}
```

## File

Use the `type="file"` attribute to create a file input.

```ts
import { html } from '@webjsdev/core';
import { fieldClass, fieldLabelClass, fieldDescriptionClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputFile() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
      <label data-slot="field-label" for="picture" class=${fieldLabelClass()}>Picture</label>
      <input data-slot="input" id="picture" type="file" class=${inputClass()}>
      <p data-slot="field-description" class=${fieldDescriptionClass()}>Select a picture to upload.</p>
    </div>
  `;
}
```

## Inline

Use `fieldClass({ orientation: 'horizontal' })` to create an inline input. Pair with a button to create a search input with a button.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { fieldClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputInline() {
  return html`
    <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
      <input data-slot="input" type="search" placeholder="Search..." aria-label="Search" class=${inputClass()}>
      <button type="button" data-slot="button" data-variant="default" data-size="default" class=${buttonClass()}>Search</button>
    </div>
  `;
}
```

## Grid

Use a grid layout to place multiple inputs side by side.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldGroupClass, fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputGrid() {
  return html`
    <div data-slot="field-group" class=${cn(fieldGroupClass(), 'grid max-w-sm grid-cols-2')}>
      <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
        <label data-slot="field-label" for="first-name" class=${fieldLabelClass()}>First Name</label>
        <input data-slot="input" id="first-name" placeholder="Jordan" class=${inputClass()}>
      </div>
      <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
        <label data-slot="field-label" for="last-name" class=${fieldLabelClass()}>Last Name</label>
        <input data-slot="input" id="last-name" placeholder="Lee" class=${inputClass()}>
      </div>
    </div>
  `;
}
```

## Required

Use the `required` attribute to indicate required inputs.

```ts
import { html } from '@webjsdev/core';
import { fieldClass, fieldLabelClass, fieldDescriptionClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputRequired() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
      <label data-slot="field-label" for="input-required" class=${fieldLabelClass()}>
        Required Field <span class="text-destructive">*</span>
      </label>
      <input data-slot="input" id="input-required" placeholder="This field is required" required class=${inputClass()}>
      <p data-slot="field-description" class=${fieldDescriptionClass()}>This field must be filled out.</p>
    </div>
  `;
}
```

## Badge

Use a `badgeClass()` element in the label to highlight a recommended field.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { badgeClass } from '#components/ui/badge.ts';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputBadge() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
      <label data-slot="field-label" for="input-badge" class=${fieldLabelClass()}>
        Webhook URL
        <span data-slot="badge" data-variant="secondary" class=${cn(badgeClass({ variant: 'secondary' }), 'ml-auto')}>
          Beta
        </span>
      </label>
      <input data-slot="input" id="input-badge" type="url" placeholder="https://api.example.com/webhook" class=${inputClass()}>
    </div>
  `;
}
```

## Input Group

To add icons, text, or buttons inside an input, use the Input Group helpers. See the [Input Group](https://webjs.dev/ui/docs/components/input-group) component for more examples.

```ts
import { html } from '@webjsdev/core';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import {
  inputGroupClass, inputGroupAddonClass, inputGroupInputClass, inputGroupTextClass,
} from '#components/ui/input-group.ts';
import { InfoIcon } from '#lib/ui/lucide.ts';

export default function InputInputGroup() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
      <label data-slot="field-label" for="input-group-url" class=${fieldLabelClass()}>Website URL</label>
      <div data-slot="input-group" role="group" class=${inputGroupClass()}>
        <input data-slot="input-group-control" id="input-group-url" placeholder="example.com" class=${inputGroupInputClass()}>
        <label data-slot="input-group-addon" data-align="inline-start" for="input-group-url" class=${inputGroupAddonClass()}>
          <span class=${inputGroupTextClass()}>https://</span>
        </label>
        <label data-slot="input-group-addon" data-align="inline-end" for="input-group-url" class=${inputGroupAddonClass({ align: 'inline-end' })}>
          ${InfoIcon()}
        </label>
      </div>
    </div>
  `;
}
```

## Button Group

To add buttons to an input, use the `buttonGroupClass()` helper. See the [Button Group](https://webjs.dev/ui/docs/components/button-group) component for more examples.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

export default function InputButtonGroup() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
      <label data-slot="field-label" for="input-button-group" class=${fieldLabelClass()}>Search</label>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <input data-slot="input" id="input-button-group" placeholder="Type to search..." class=${inputClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Search</button>
      </div>
    </div>
  `;
}
```

## Form

A full form example with multiple inputs, a select, and a button.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import {
  fieldGroupClass, fieldClass, fieldLabelClass, fieldDescriptionClass,
} from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';
import { selectTriggerClass } from '#components/ui/select.ts';

export default function InputForm() {
  return html`
    <form class="w-full max-w-sm">
      <div data-slot="field-group" class=${fieldGroupClass()}>
        <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
          <label data-slot="field-label" for="form-name" class=${fieldLabelClass()}>Name</label>
          <input data-slot="input" id="form-name" type="text" placeholder="Evil Rabbit" required class=${inputClass()}>
        </div>
        <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
          <label data-slot="field-label" for="form-email" class=${fieldLabelClass()}>Email</label>
          <input data-slot="input" id="form-email" type="email" placeholder="john@example.com" class=${inputClass()}>
          <p data-slot="field-description" class=${fieldDescriptionClass()}>
            We&apos;ll never share your email with anyone.
          </p>
        </div>
        <div class="grid grid-cols-2 gap-4">
          <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
            <label data-slot="field-label" for="form-phone" class=${fieldLabelClass()}>Phone</label>
            <input data-slot="input" id="form-phone" type="tel" placeholder="+1 (555) 123-4567" class=${inputClass()}>
          </div>
          <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
            <label data-slot="field-label" for="form-country" class=${fieldLabelClass()}>Country</label>
            <ui-select>
              <select id="form-country" class=${selectTriggerClass()}>
                <option value="us" selected>United States</option>
                <option value="uk">United Kingdom</option>
                <option value="ca">Canada</option>
              </select>
            </ui-select>
          </div>
        </div>
        <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
          <label data-slot="field-label" for="form-address" class=${fieldLabelClass()}>Address</label>
          <input data-slot="input" id="form-address" type="text" placeholder="123 Main St" class=${inputClass()}>
        </div>
        <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>
            Cancel
          </button>
          <button type="submit" data-slot="button" data-variant="default" data-size="default" class=${buttonClass()}>Submit</button>
        </div>
      </div>
    </form>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { fieldClass, fieldLabelClass, fieldDescriptionClass } from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      apiKey: 'API Key',
      placeholder: 'sk-...',
      description: 'Your API key is encrypted and stored securely.',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      apiKey: 'مفتاح API',
      placeholder: 'sk-...',
      description: 'مفتاح API الخاص بك مشفر ومخزن بأمان.',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      apiKey: 'מפתח API',
      placeholder: 'sk-...',
      description: 'מפתח ה-API שלך מוצפן ונשמר בצורה מאובטחת.',
    },
  },
};

export default function InputRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div role="group" data-slot="field" data-orientation="vertical" dir=${dir} lang=${lang} class=${fieldClass()}>
      <label data-slot="field-label" for="input-rtl-api-key" class=${fieldLabelClass()}>${t.apiKey}</label>
      <input data-slot="input" id="input-rtl-api-key" type="password" placeholder=${t.placeholder} class=${inputClass()}>
      <p data-slot="field-description" class=${fieldDescriptionClass()}>${t.description}</p>
    </div>
  `;
}
```
