# Text field
> Form-associated text field with a comet of light on the border while focused; invalid values turn the border to static.
- Element: `<hf-input>`
- React: `import { HfInput } from "@/components/lumesec/hf-input"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-input.json
- Page: https://elements.lumesec.ai/components/pixel-hd/input



Live preview: https://elements.lumesec.ai/view/hf-input

```html
<hf-input name="email" label="Work email" type="email" required placeholder="you@company.com" hint="We’ll send the invite here"></hf-input>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/hf-input
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-input.json
```

## Usage

React:

```tsx
import { HfInput } from "@/components/lumesec/hf-input";

export function Example() {
  return (
    <HfInput name="email" label="Work email" type="email" required placeholder="you@company.com" hint="We’ll send the invite here" />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-input.js"></script>

<hf-input name="email" label="Work email" type="email" required placeholder="you@company.com" hint="We’ll send the invite here"></hf-input>
```

## Behaviour

A comet of light runs around the border while you type and sparks off the caret. Invalid input turns the border into static; a valid value gets a green sweep.

## API reference

### Attributes

| Attribute      | React prop     | Type      | Default | Description                                                                                                                |
| -------------- | -------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `label`        | `label`        | `string`  | —       | Visible label, linked to the inner input. Hidden when absent.                                                              |
| `value`        | `value`        | `string`  | —       | Initial value. Also the value restored on form reset.                                                                      |
| `hint`         | `hint`         | `string`  | —       | Text under the field when there is no error.                                                                               |
| `error`        | `error`        | `string`  | —       | Message shown, and used as the validation message, when the value is invalid. Defaults to the browser `validationMessage`. |
| `success`      | `success`      | `string`  | —       | Message shown when a valid value is committed on blur. Falls back to `hint`.                                               |
| `name`         | `name`         | `string`  | —       | Form field name.                                                                                                           |
| `type`         | `type`         | `string`  | —       | Passed to the inner `<input>`, for example `email`, `url` or `password`.                                                   |
| `placeholder`  | `placeholder`  | `string`  | —       | Passed to the inner input.                                                                                                 |
| `required`     | `required`     | `boolean` | `false` | Presence attribute, passed to the inner input.                                                                             |
| `pattern`      | `pattern`      | `string`  | —       | Passed to the inner input.                                                                                                 |
| `minlength`    | `minlength`    | `number`  | —       | Passed to the inner input.                                                                                                 |
| `maxlength`    | `maxlength`    | `number`  | —       | Passed to the inner input.                                                                                                 |
| `autocomplete` | `autocomplete` | `string`  | —       | Passed to the inner input.                                                                                                 |
| `inputmode`    | `inputmode`    | `string`  | —       | Passed to the inner input.                                                                                                 |
| `spellcheck`   | `spellcheck`   | `string`  | —       | Passed to the inner input.                                                                                                 |

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event    | React prop | Detail              | Description                                                         |
| -------- | ---------- | ------------------- | ------------------------------------------------------------------- |
| `input`  | `onInput`  | `{ value: string }` | Fires on every edit.                                                |
| `change` | `onChange` | `{ value: string }` | Fires when the inner input commits a change, on blur after editing. |

### Methods

Call them on the element, for example through a React ref.

| Method    | Description                     |
| --------- | ------------------------------- |
| `focus()` | Moves focus to the inner input. |

### Properties

| Property | Type     | Description                                                                                        |
| -------- | -------- | -------------------------------------------------------------------------------------------------- |
| `value`  | `string` | Current text. Setting it updates the form value and validity, but not the visual state or message. |

## Accessibility

* A `<label for>` in the shadow root names the inner `<input>`.
* The hint, error and success text sits in an `aria-live="polite"` region.
* Sets `aria-invalid` on the inner input when it validates on blur.
* The host does not delegate focus; call `focus()` on it to focus the input.
* Submits the inner input value under `name`. Validity mirrors the inner input constraints (`required`, `type`, `pattern`, `minlength`, `maxlength`) and reports `customError` with the `error` text or the browser message. The error or success state appears on blur, and while in error it re-checks on every edit. Form reset restores the `value` attribute.
* Reduced motion: the border comet stays in one place, the error static does not flicker, the caret sparks and error shake are skipped, and messages swap without rolling.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--card`, `--destructive`, `--foreground`, `--lumesec`, `--lumesec-success` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-danger`, `--ui-fg`, `--ui-muted`, `--ui-ok` and `--ui-surface`.

## Notes

* Attributes are read once on first connect and are not observed; use the `value` property afterwards.
* The inner input's native `input` event is composed, so an `input` listener on the host also receives that event (without `detail`) in addition to the custom one.