---
title: Input
description: Edit single-line text with native input events and Field integration.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Input

> Edit single-line text with native input events and Field integration.

## Anatomy

```text
Input [component; slot=root; <input>]
```

## Usage

Use Input for native single-line text editing. Compose it with [Field](https://moraine.subf.dev/components/field.md) for a
label and validation message, or [InputGroup](https://moraine.subf.dev/components/input-group.md) for adjacent addons. Use
[Textarea](https://moraine.subf.dev/components/textarea.md) for multi-line text and [NumberInput](https://moraine.subf.dev/components/number-input.md)
for a constrained numeric stepper.

```tsx
import { Field, Input } from 'moraine'

export function Example() {
  return (
    <Field label="Your name">
      <Input placeholder="Your name" />
    </Field>
  )
}
```

### Native input behavior

`Input` forwards native input attributes. Use `value` with `onValueChange` for controlled text and
`defaultValue` for an initial uncontrolled value; a native form reset restores `defaultValue`.
`value={undefined}` leaves the input uncontrolled, and a controlled input restores its displayed text
to `value` after every edit, so update `value` from `onValueChange`. `readOnly` keeps the field
focusable without allowing edits; `disabled` removes it from interaction. `autocomplete` defaults to
`'off'`.

```tsx
<Input value={query()} onValueChange={setQuery} placeholder="Search projects..." />
```

Inside a [Field](https://moraine.subf.dev/components/field.md), Input inherits `size`, `required`, `disabled`, and `readOnly`,
takes its `name` from the field when it sets none, and links the label, description, and error
through ARIA attributes. Set `variant` (`'outline'`, `'subtle'`, `'ghost'`, or `'none'`) and `size`
(`'sm'`, `'md'`, or `'lg'`) to change its presentation.

### Value modifiers

`modifiers` transforms the text before it reaches `onValueChange` and form state, and sets the
callback's value type.

| Modifier | Effect                                                                            |
| -------- | --------------------------------------------------------------------------------- |
| `trim`   | Strips surrounding whitespace, also from the displayed text on `change`           |
| `lazy`   | Updates the value on `change` (blur or Enter) instead of on every keystroke       |
| `number` | Parses the text to a `number`; non-numeric text gives `undefined`                 |
| `empty`  | `'null'` or `'undefined'` turns empty text into that value; `'preserve'` keeps it |

```tsx
<Input modifiers={{ number: true, empty: 'null' }} onValueChange={(value) => setAge(value)} />
```

Here `value` is `number | null`. Use [NumberInput](https://moraine.subf.dev/components/number-input.md) when the user needs
stepping, bounds, or formatting.

### Composed controls

Use `InputGroup.Leading` and `InputGroup.Trailing` for static context such as an icon or unit.
Password visibility, clearing, copying, and loading stay in your application: compose buttons and
icons into these parts and provide their labels and handlers.

```tsx
<InputGroup>
  <InputGroup.Leading>
    <Icon name="i-lucide:key-round" />
  </InputGroup.Leading>
  <Input type={showPassword() ? 'text' : 'password'} placeholder="Enter secret token" />
  <InputGroup.Trailing compact>
    <Button
      variant="ghost"
      size="icon-sm"
      onClick={() => setShowPassword((prev) => !prev)}
      aria-label={showPassword() ? 'Hide token' : 'Show token'}
    />
  </InputGroup.Trailing>
</InputGroup>
```

## Examples

### Filter a project list

Keep the query in local state with `value` and `onValueChange`. Filter the list from that string.

```tsx
import { Field, Input } from 'moraine'
import { createMemo, createSignal, For, Show } from 'solid-js'

const PROJECTS = ['Atlas design system', 'Billing portal', 'Customer dashboard', 'Release tracker']

export function ControlledInput() {
  const [query, setQuery] = createSignal('')
  const matches = createMemo(() =>
    PROJECTS.filter((project) => project.toLowerCase().includes(query().trim().toLowerCase())),
  )

  return (
    <div class="max-w-md w-full space-y-3">
      <Field label="Find a project">
        <Input value={query()} onValueChange={setQuery} placeholder="Search projects..." />
      </Field>
      <Show when={matches().length} fallback={<p class="text-sm">No matching projects.</p>}>
        <ul class="text-sm divide-border divide-y">
          <For each={matches()}>{(project) => <li class="py-2">{project}</li>}</For>
        </ul>
      </Show>
    </div>
  )
}
```

### Reveal a deploy token

Compose the visibility toggle yourself. InputGroup does not own the show/hide state or the
button's label.

```tsx
import { Button, Icon, Input, InputGroup } from 'moraine'
import { createSignal } from 'solid-js'

export function ComposedControls() {
  const [showPassword, setShowPassword] = createSignal(false)

  return (
    <div class="max-w-md w-full space-y-4">
      <InputGroup>
        <InputGroup.Leading>
          <Icon name="i-lucide:key-round" />
        </InputGroup.Leading>
        <Input type={showPassword() ? 'text' : 'password'} placeholder="Enter secret token" />
        <InputGroup.Trailing compact>
          <Button
            variant="ghost"
            size="icon-sm"
            onClick={() => setShowPassword((prev) => !prev)}
            aria-label={showPassword() ? 'Hide token' : 'Show token'}
          >
            <Icon name={showPassword() ? 'i-lucide:eye-off' : 'i-lucide:eye'} />
          </Button>
        </InputGroup.Trailing>
      </InputGroup>
    </div>
  )
}
```

### Password, search, URL, and price fields

Compose `InputGroup` addons around Input. Your application owns visibility toggles, clear buttons,
and unit suffixes.

```tsx
import { Button, Icon, Input, InputGroup } from 'moraine'
import { createSignal, Show } from 'solid-js'

export function InputWithIcons() {
  const [showPassword, setShowPassword] = createSignal(false)
  const [query, setQuery] = createSignal('SolidJS reactive components')

  return (
    <div class="flex flex-col gap-4 max-w-sm w-full">
      <InputGroup>
        <InputGroup.Leading>
          <Icon name="i-lucide:lock" />
        </InputGroup.Leading>
        <Input
          type={showPassword() ? 'text' : 'password'}
          defaultValue="my_super_secret_token_123"
          placeholder="Enter password"
        />
        <InputGroup.Trailing compact>
          <Button
            variant="ghost"
            size="icon-sm"
            onClick={() => setShowPassword((prev) => !prev)}
            aria-label={showPassword() ? 'Hide password' : 'Show password'}
          >
            <Icon name={showPassword() ? 'i-lucide:eye-off' : 'i-lucide:eye'} />
          </Button>
        </InputGroup.Trailing>
      </InputGroup>

      <InputGroup>
        <InputGroup.Leading>
          <Icon name="i-lucide:search" />
        </InputGroup.Leading>
        <Input
          value={query()}
          onInput={(e) => setQuery(e.currentTarget.value)}
          placeholder="Search documents..."
        />
        <InputGroup.Trailing compact>
          <Show when={query()}>
            <Button
              variant="ghost"
              size="icon-sm"
              onClick={() => setQuery('')}
              aria-label="Clear search"
            >
              <Icon name="i-lucide:x" />
            </Button>
          </Show>
        </InputGroup.Trailing>
      </InputGroup>

      <InputGroup>
        <InputGroup.Leading compact>
          <div class="text-xs text-muted-foreground font-mono flex gap-1 items-center">
            <Icon name="i-lucide:globe" class="size-3.5" />
            https://
          </div>
        </InputGroup.Leading>
        <Input placeholder="project-slug" />
        <InputGroup.Trailing compact>
          <span class="text-xs text-muted-foreground font-mono">.moraine.dev</span>
        </InputGroup.Trailing>
      </InputGroup>

      <InputGroup>
        <InputGroup.Leading>
          <span class="text-xs text-muted-foreground font-semibold">$</span>
        </InputGroup.Leading>
        <Input defaultValue="49.00" placeholder="0.00" />
        <InputGroup.Trailing>
          <span class="text-xs text-muted-foreground">USD / mo</span>
        </InputGroup.Trailing>
      </InputGroup>
    </div>
  )
}
```

### Validate a work email

Bind Input to `form.Field` so schema validation owns the error. Omit `name` on the input; the
bound field supplies it.

```tsx
import { Button, createForm, Input, InputGroup, Icon } from 'moraine'
import { createSignal } from 'solid-js'
import * as v from 'valibot'

export function FormIntegration() {
  const [submittedEmail, setSubmittedEmail] = createSignal('')
  const form = createForm({
    schema: v.object({
      email: v.pipe(v.string(), v.email('Please enter a valid work email address.')),
    }),
    initialInput: { email: '' },
    validate: 'input',
  })

  return (
    <form.Form onSubmit={(output) => setSubmittedEmail(output.email)}>
      <div class="max-w-xl space-y-4">
        <form.Field
          name="email"
          label="Work Email"
          description="We will send your verification link here."
          required
        >
          <InputGroup>
            <InputGroup.Leading>
              <Icon name="i-lucide:mail" />
            </InputGroup.Leading>
            <Input type="email" placeholder="alex@company.com" />
          </InputGroup>
        </form.Field>
        <div class="flex gap-3 items-center">
          <Button type="submit" variant="soft" tone="neutral" size="sm">
            Validate
          </Button>
          <p class="text-xs text-muted-foreground">Submitted: {submittedEmail() || 'none'}</p>
        </div>
      </div>
    </form.Form>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-disabled` | `input` | Present when the component, slot, or item is disabled. |
| `data-invalid` | `input` | Present when the field or form has a validation error. |
| `data-readonly` | `input` | Present when the field is in read-only mode. |
| `data-required` | `input` | Present when the field input is required. |

### Props

Props for the Input component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| autocomplete | JSX.InputHTMLAttributes<HTMLInputElement>['autocomplete'] \| undefined | 'off' | The native `autocomplete` attribute, such as `'email'` or `'current-password'`. Browser<br>autofill is off unless set. |
| autofocus | boolean \| undefined | false | Whether the input is focused after mounting, by script rather than the native `autofocus`<br>attribute. Focus is skipped when the input is disabled, and `autofocusDelay` postpones it. |
| autofocusDelay | number \| undefined | 0 | Delay in milliseconds between mount and focusing the input. Only used with `autofocus`. |
| defaultValue | Value \| undefined | — | Initial value for uncontrolled usage. Also the value restored when the owning form is reset. |
| disabled | boolean \| undefined | false | Whether the control is disabled: it cannot be interacted with and sets `aria-disabled`.<br>When omitted, the control inherits `disabled` from the surrounding `Field`; an explicit<br>`false` overrides the `Field`. |
| id | string \| undefined | — | The ID of the control's main focusable element, which a surrounding `Field` label points to<br>with `for`. A unique ID is generated when omitted. The control's related parts (hidden<br>input, label, description) derive their IDs from it, so keep it unique on the page. |
| maxLength | number \| string \| undefined | — | Native `maxlength`: the maximum number of characters the user can type. Numeric strings are accepted. |
| modifiers | TModifiers \| undefined | — | Transforms the text before it reaches `onValueChange` and form state, and sets the callback's<br>value type.<br><br>- `trim`: strips surrounding whitespace, also from the displayed text on `change` (blur or Enter).<br>- `lazy`: updates the value on `change` instead of on every keystroke.<br>- `number`: parses the text to a `number`; non-numeric text gives `undefined`, and empty text follows `empty`.<br>- `empty`: `'null'` or `'undefined'` turns an empty (whitespace-only) string into that value; `'preserve'` keeps the string. |
| name | string \| undefined | — | The name of the control, used for native form submission. When omitted, the control uses<br>the name of its form binding or a string `name` set on the surrounding `Field`. |
| onBlur | JSX.FocusEventHandlerUnion<HTMLInputElement, FocusEvent> \| undefined | — | Event handler for the blur event. |
| onChange | JSX.EventHandlerUnion<HTMLInputElement, Event> \| undefined | — | Native change event, after value synchronization and Field notification. |
| onFocus | JSX.FocusEventHandlerUnion<HTMLInputElement, FocusEvent> \| undefined | — | Event handler for the focus event. |
| onInput | JSX.InputEventHandlerUnion<HTMLInputElement, InputEvent> \| undefined | — | Native `input` event handler, called after the component has handled the event. It fires on every keystroke, also with `modifiers.lazy`. |
| onValueChange | ((value: ModifierValue<TModifiers>) => void) \| undefined | — | Called with the new value, after `modifiers` are applied, as the user edits. It fires on<br>every keystroke, or on `change` (blur or Enter) with `modifiers.lazy`. Its argument type<br>follows `modifiers`: `string` by default, `number` with `number`, and may include `null`<br>or `undefined` through `empty`. |
| placeholder | string \| undefined | — | Hint text shown while the input is empty. It is not a substitute for a label. |
| readOnly | boolean \| undefined | false | Whether the control is read-only: the value is visible and focusable but cannot be changed,<br>and `aria-readonly` is set. When omitted, the control inherits `readOnly` from the<br>surrounding `Field`. |
| ref | Ref<HTMLInputElement> \| undefined | — | Ref callback or variable that receives the native `<input>` element. |
| required | boolean \| undefined | false | Whether the control is required, which sets `aria-required` (and the native `required`<br>attribute where the control renders a native input). When omitted, the control inherits<br>`required` from the surrounding `Field`. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| type | JSX.InputHTMLAttributes<HTMLInputElement>['type'] \| undefined | 'text' | The native `type` of the input element, such as `'email'`, `'password'`, or `'search'`. |
| value | Value \| undefined | — | The current value (controlled). `undefined` leaves the input uncontrolled; the displayed<br>text is restored to this value after every edit, so update it from `onValueChange`. |
| variant | 'outline' \| 'subtle' \| 'ghost' \| 'none' \| undefined | 'outline' | Visual treatment of the component. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`modifiers` example**

```tsx
import { Input } from 'moraine'

<Input
  modifiers={{ number: true, empty: 'null' }}
  onValueChange={(value) => console.log(value)} // number | null
/>
```
