# Input Primitive

Input is a Starwind Runtime primitive in the form-value-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## 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>
```

### Vue
Use the Vue 3.5 beta adapter to render Input anatomy.
```vue
<script setup lang="ts">
import Input from "@starwind-ui/vue/input";
</script>

<template>
  <Input.Root placeholder="Email" />
</template>
```
## 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 | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| value | `InputValue` | - | control | Controls the current Input value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for state changes.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** listen for starwind:value-change and call setValue for later updates. |
| defaultValue | `InputValue` | - | control | Sets the initial Input value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for state changes.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** listen for starwind:value-change and call setValue for later updates. |
| 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. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for state changes.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** listen for starwind:value-change and call setValue for later updates. |
#### 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:** Use value for controlled state and defaultValue for default state, and onValueChange for state changes.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** listen for starwind:value-change and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 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` |
## Changelog
### v1.0.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced value synchronization and Runtime state while preserving native input attributes and events.