# TextField (`text-field`) - SignalOS widget

> Labeled text input with size variants, helper/error text, and common HTML input event handlers.

- **Version:** 0.1.3
- **Kind:** widget · **Category:** inputs
- **Install:** `npx shadcn@latest add @signalos/text-field`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils, @signalos/skeleton
- **npm dependencies:** lucide-react@^1.7.0
- **Files installed:** `src/components/widgets/text-field/TextField.tsx`, `src/components/widgets/text-field/TextField.types.ts`, `src/components/widgets/text-field/TextField.utils.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
import { TextField } from "@/components/widgets/text-field/TextField"
```

## Example

```tsx
import * as React from "react"
import { Mail } from "lucide-react"

import { TextField } from "./TextField"

export default function Example() {
  const [email, setEmail] = React.useState("")

  return (
    <div className="max-w-sm">
      <TextField
        label="Email"
        type="email"
        placeholder="Enter your email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        leadingIcon={<Mail className="h-4 w-4" />}
        helperText="We'll never share your email."
      />
    </div>
  )
}
```

## Props

### `TextFieldSize`

```ts
export type TextFieldSize = "sm" | "md" | "lg"
```

### `BaseInputProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string \| undefined` | no | - | Unique identifier for the input.  Used to associate the input with a `<label>` using the `htmlFor` attribute. |
| `name` | `string \| undefined` | no | - | Name of the input.  Used when submitting forms. |
| `type` | `HTMLInputTypeAttribute \| undefined` | no | - | Specifies the type of input.  Common values: - `"text"` - `"email"` - `"password"` - `"number"` - `"search"` - `"tel"` - `"url"` |
| `value` | `string \| number \| readonly string[] \| undefined` | no | - | Current controlled value of the input. |
| `defaultValue` | `string \| number \| readonly string[] \| undefined` | no | - | Initial value for an uncontrolled input. |
| `placeholder` | `string \| undefined` | no | - | Placeholder text displayed when the input is empty. |
| `disabled` | `boolean \| undefined` | no | - | Disables the input.  The user cannot edit or focus the field. |
| `required` | `boolean \| undefined` | no | - | Marks the field as required.  Used for form validation. |
| `readOnly` | `boolean \| undefined` | no | - | Makes the input read-only.  Users can focus and copy the value but cannot edit it. |
| `autoComplete` | `string \| undefined` | no | - | Enables browser autocomplete.  Example: - `"email"` - `"username"` - `"current-password"` |
| `autoFocus` | `boolean \| undefined` | no | - | Automatically focuses the input when the component is mounted. |
| `maxLength` | `number \| undefined` | no | - | Maximum number of characters allowed. |
| `minLength` | `number \| undefined` | no | - | Minimum number of characters required. |
| `min` | `string \| number \| undefined` | no | - | Minimum numeric value.  Used with number inputs. |
| `max` | `string \| number \| undefined` | no | - | Maximum numeric value.  Used with number inputs. |
| `step` | `string \| number \| undefined` | no | - | Increment/decrement interval.  Used with number inputs. |
| `pattern` | `string \| undefined` | no | - | Regular expression used for validation. |
| `inputMode` | `"text" \| "url" \| "none" \| "search" \| "tel" \| "email" \| "numeric" \| "decimal" \| undefined` | no | - | Hints the appropriate keyboard on mobile devices.  Example: - `"numeric"` - `"decimal"` - `"email"` |
| `onChange` | `ChangeEventHandler<HTMLInputElement> \| undefined` | no | - | Called whenever the input value changes. |
| `onFocus` | `FocusEventHandler<HTMLInputElement> \| undefined` | no | - | Called when the input receives focus. |
| `onBlur` | `FocusEventHandler<HTMLInputElement> \| undefined` | no | - | Called when the input loses focus. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement> \| undefined` | no | - | Called when a keyboard key is pressed down. |
| `onKeyUp` | `KeyboardEventHandler<HTMLInputElement> \| undefined` | no | - | Called when a keyboard key is released. |

### `TextFieldProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | `ReactNode` | no | - | Label displayed above the input. |
| `helperText` | `ReactNode` | no | - | Helper text displayed below the input.  Usually used for hints or descriptions. |
| `error` | `ReactNode` | no | - | Error message displayed below the input.  Usually styled in red. |
| `size` | `TextFieldSize \| undefined` | no | - | Controls the overall size of the input.  - `sm` → Small - `md` → Medium (default) - `lg` → Large |
| `loading` | `boolean \| undefined` | no | - | Displays a loading state.  Typically shows a loading skeleton or spinner and disables interaction. |
| `linkText` | `ReactNode` | no | - | Optional clickable text displayed next to the label.  Example: "Forgot Password?" |
| `onLinkClick` | `(() => void) \| undefined` | no | - | Callback fired when the link text is clicked. |
| `leadingIcon` | `ReactNode` | no | - | Icon displayed at the beginning of the input.  Example: `<Search />` |
| `trailingIcon` | `ReactNode` | no | - | Icon displayed at the end of the input.  Example: `<Eye />` |
| `containerClassName` | `string \| undefined` | no | - | Additional classes for the outer container. |
| `labelClassName` | `string \| undefined` | no | - | Additional classes for the label. |
| `className` | `string \| undefined` | no | - | Additional classes for the input element. |
| `data-testid` | `string \| undefined` | no | - | Test identifier used by automated testing tools.  Example: `data-testid="email-input"` |
| `id` | `string \| undefined` | no | - | Unique identifier for the input.  Used to associate the input with a `<label>` using the `htmlFor` attribute. |
| `name` | `string \| undefined` | no | - | Name of the input.  Used when submitting forms. |
| `type` | `HTMLInputTypeAttribute \| undefined` | no | - | Specifies the type of input.  Common values: - `"text"` - `"email"` - `"password"` - `"number"` - `"search"` - `"tel"` - `"url"` |
| `value` | `string \| number \| readonly string[] \| undefined` | no | - | Current controlled value of the input. |
| `defaultValue` | `string \| number \| readonly string[] \| undefined` | no | - | Initial value for an uncontrolled input. |
| `placeholder` | `string \| undefined` | no | - | Placeholder text displayed when the input is empty. |
| `disabled` | `boolean \| undefined` | no | - | Disables the input.  The user cannot edit or focus the field. |
| `required` | `boolean \| undefined` | no | - | Marks the field as required.  Used for form validation. |
| `readOnly` | `boolean \| undefined` | no | - | Makes the input read-only.  Users can focus and copy the value but cannot edit it. |
| `autoComplete` | `string \| undefined` | no | - | Enables browser autocomplete.  Example: - `"email"` - `"username"` - `"current-password"` |
| `autoFocus` | `boolean \| undefined` | no | - | Automatically focuses the input when the component is mounted. |
| `maxLength` | `number \| undefined` | no | - | Maximum number of characters allowed. |
| `minLength` | `number \| undefined` | no | - | Minimum number of characters required. |
| `min` | `string \| number \| undefined` | no | - | Minimum numeric value.  Used with number inputs. |
| `max` | `string \| number \| undefined` | no | - | Maximum numeric value.  Used with number inputs. |
| `step` | `string \| number \| undefined` | no | - | Increment/decrement interval.  Used with number inputs. |
| `pattern` | `string \| undefined` | no | - | Regular expression used for validation. |
| `inputMode` | `"text" \| "url" \| "none" \| "search" \| "tel" \| "email" \| "numeric" \| "decimal" \| undefined` | no | - | Hints the appropriate keyboard on mobile devices.  Example: - `"numeric"` - `"decimal"` - `"email"` |
| `onChange` | `ChangeEventHandler<HTMLInputElement> \| undefined` | no | - | Called whenever the input value changes. |
| `onFocus` | `FocusEventHandler<HTMLInputElement> \| undefined` | no | - | Called when the input receives focus. |
| `onBlur` | `FocusEventHandler<HTMLInputElement> \| undefined` | no | - | Called when the input loses focus. |
| `onKeyDown` | `KeyboardEventHandler<HTMLInputElement> \| undefined` | no | - | Called when a keyboard key is pressed down. |
| `onKeyUp` | `KeyboardEventHandler<HTMLInputElement> \| undefined` | no | - | Called when a keyboard key is released. |

## Changelog

# text-field
## 0.1.3

- Conditional rendering added for the error and help-text slots.
## 0.1.2

- Content sync fix to bring source in line with published registry payload.


## 0.1.1

- Minor updates.

## 0.1.0

- Initial release.