# Input Primitive

Input is a Starwind Runtime primitive in the form-value-control contract family.
## Anatomy
### Astro
Use the Astro primitive adapter to render Input anatomy with the Runtime wiring included.
```astro
---
import { Input } from "@starwind-ui/astro/input";
---

<Input.Root placeholder="Email" />
```

### React
Use the React primitive adapter when Input state participates in React rendering.
```tsx
import { Input } from "@starwind-ui/react/input";

export function Example() {
  return (
    <Input.Root placeholder="Email" />
  );
}
```

### HTML
Render the Input data-sw-* contract yourself, then initialize createInput.
```html
<input data-sw-input placeholder="Email" />

<script type="module">
  import { createInput } from "@starwind-ui/runtime/input";

  const root = document.querySelector("[data-sw-input]");
  if (root) {
    createInput(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Input Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-input` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| value | `InputValue` | - | control | Controls the current Input value. |
| defaultValue | `InputValue` | - | control | Sets the initial Input value for uncontrolled usage. |
| disabled | `boolean` | false | option | Disables the Root part. |
| name | `string` | - | attribute | Sets the submitted form field name. |
| required | `boolean` | - | attribute | Marks the form control as required. |
| onValueChange | `(value: string, details: InputValueChangeDetails) => void` | - | callback | Runs when the Input value changes. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-input` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| value | `InputValue` | value | defaultValue | - | `getValue` | `setValue` | Tracks the current Input value. | React supports controlled and default state with value and defaultValue props. Runtime/HTML emits starwind:value-change and updates with setValue. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| valueChange | onValueChange | starwind:value-change | value: `string` | InputValueChangeDetails | - | - | Fires when the value changes for Input. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setValue` | state: value | emit: false | Yes | Updates the current Input value from Runtime code. |
| `setDisabled` | prop: disabled | - | No | Updates whether Input is disabled from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-input`, `data-disabled`, `disabled`, `value` | The native input must participate in forms and expose disabled/value state before the controller attaches. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | name, required, value |
| Hidden input | - |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createInput`](/docs/runtime/#create-input) |
| Import | `@starwind-ui/runtime/input` |
| Root part | root |
| Option props | defaultValue, disabled, onValueChange, value |
| Option lifecycles | - |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | name, required, value |
| Hidden input | - |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Input](/docs/components/input/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/input` | `createInput` |
| Astro Primitive | `@starwind-ui/astro/input` | `Input`, `InputRoot` |
| React Primitive | `@starwind-ui/react/input` | `Input`, `InputRoot` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Input` |
| runtime-factory | `createInput` |
| part | `Input.Root` |