Site color

Choose your site’s color palette.

Saved on this device.

FormInputField

FormInputFieldNative input

A useful label, a familiar control, and a value you can work with. Explore every native input type and appearance.

Forms & input

Edit workspace details

Type an email, adjust the seat count and lock the fields. The summary reads the same refs as the inputs.

FormInputField in contextCOMPOSITION

Edit the email, step the seat count, and lock the fields. The feedback follows the reactive values.

<RegorApp id="form-input-field-demo" src="./playground.ts"/>
import {
  defineButtonComponents,
  defineFlexComponents,
  defineFormComponents,
  defineFormInputField,
  defineGridComponents,
  defineIconComponents,
  definePanelComponents,
} from '@purestack/ts-components'
import { lucide_mail } from '@purestack/ts-svg-icons'
import {
  type ComputedRef,
  computed,
  createApp,
  defineComponent,
  html,
  type Ref,
  ref,
} from 'regor'
import { mountFormAppearanceGalleries } from '../appearance'

export interface FormInputFieldExample {
  contactEmail: Ref<string>
  seats: Ref<number | string>
  locked: Ref<boolean>
  summary: ComputedRef<string>
}

const formInputFieldExampleTemplate = html`<Flex direction="column">
  <Grid columns="1" columnsSm="2">
    <FormInputField
      id="input-email"
      label="Contact email"
      name="email"
      type="email"
      autocomplete="email"
      icon="lucide:mail"
      placeholder="you@example.com"
      :model="contactEmail"
      :disabled="locked"/>
    <FormInputField
      id="input-seats"
      label="Seats"
      type="number"
      min="1"
      step="1"
      :model="seats"
      :disabled="locked"/>
  </Grid>
  <FormCheck id="input-lock" label="Lock fields" :checked="locked"/>
  <FormStatus>{{ summary }}</FormStatus>
</Flex>`

function createFormInputFieldExample(): FormInputFieldExample {
  const contactEmail = ref('')
  const seats = ref<number | string>(3)
  const locked = ref(false)
  return {
    contactEmail,
    seats,
    locked,
    summary: computed(
      () => `${seats()} seats · ${contactEmail() || 'No email entered'}`,
    ),
  }
}

const component = defineComponent<FormInputFieldExample>(
  formInputFieldExampleTemplate,
  {
    context: createFormInputFieldExample,
  },
)
const icons: Record<string, string> = { 'lucide:mail': lucide_mail }

createApp(
  {
    components: {
      FormInputFieldExample: component,

      ...defineFlexComponents(),
      ...definePanelComponents(),
      ...defineButtonComponents(),
      ...defineFormComponents(),
      ...defineFormInputField(),
      ...defineGridComponents(),
      ...defineIconComponents((name) => icons[name] ?? ''),
    },
  },
  {
    selector: 'app#form-input-field-demo',
    template: html`<FormInputFieldExample/>`,
  },
)

mountFormAppearanceGalleries()

Native input types

Use browser-native controls for dates, passwords and other structured input.

<Grid columns="1" columnsSm="2">
  <FormInputField id="input-date" label="Review date" type="date" />
  <FormInputField
    id="input-password"
    label="New password"
    type="password"
    autocomplete="new-password"
    placeholder="Enter a password"
  />
</Grid>

All semantic tones

All ten tones are visible at once. The control’s label and content explain the intent independently of color.

All ten semantic tonesCOMPOSITION

Each sample is interactive and keeps its own local state. Switch the site theme to compare both palettes.

All visual variants

All eighteen supported treatments, shown in accent. Tone and variant are independent, so any treatment can be combined with a semantic tone.

All eighteen visual variantsCOMPOSITION

Each sample is interactive and keeps its own local state. Switch the site theme to compare both palettes.

Every native input type

All thirteen supported types are visible. Browser presentation differs by platform; numeric step buttons run in the mounted sample.

All thirteen input typesCOMPOSITION

Each sample is interactive and keeps its own local state. Switch the site theme to compare both palettes.

Labels, icons, and availability

Combine a visible label with useful input hints. required and disabled are booleans; icons may appear at either edge.

Labels, icons, and availabilityCOMPOSITION
Required
Disabled
Start icon
End icon
Both edges

Compare all values together. Use the live examples for application state and event handling.

Value and numeric controls

Bind model to a string or number ref. Numeric fields add increment and decrement controls; min bounds the result and step controls the amount. Ordinary attributes such as maxlength, pattern, aria-describedby, and inputmode reach the native input.

<FormInputField id="seat-count" label="Seats" type="number" name="seats"
  :model="seats" min="1" step="2" :required="true"/>
<FormInputField id="project-code" label="Project code" :model="code"
  maxlength="12" pattern="[A-Za-z0-9-]+" aria-describedby="code-help"/>
<p id="code-help">Use letters, numbers, or a hyphen.</p>

Behavior and accessibility

Visible labels are associated with generated or explicit IDs. Extra native attributes and events are inherited by the input. Number step buttons clamp to min; max and other native constraints still need form validation. Bind a ref rather than an evaluated ref value.

API reference

FormInputField contract

Props below are the public template API. RefOrValue accepts a literal or a reactive ref; bind refs with a colon-prefixed attribute. Native attributes and events can be passed through the component root.

id

string
Default
generated

Unique control ID. Supply an explicit value when help text or another element needs to reference this control.

label

RefOrValue<string>
Default
not set

Visible label. Use language that describes the control or value in its surrounding context.

tone

RefOrValue<SemanticTone>
Default
inherited

Semantic intent: neutral, accent, secondary, info, success, warning, danger, feature, custom or ghost. The active skin supplies the colors.

variant

RefOrValue<ComponentVariant>
Default
surfaceAlt

Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, flat, flatAlt, flatSolid, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.

model

Ref<string | number>
Default
ref('')

Two-way value ref. Pass the ref itself with :model="fieldValue" so edits update application state.

type

RefOrValue<FormInputFieldType>
Default
text

Native input type: text, email, password, number, tel, url, search, date, time, datetime-local, month, week or color.

name

RefOrValue<string>
Default
not set

Native form field name used during FormData serialization.

required

RefOrValue<boolean>
Default
false

Native required constraint. Validate the owning form before accepting its data.

autocomplete

RefOrValue<string>
Default
off

Native browser autofill hint, such as name, email or current-password.

min

RefOrValue<number | string>
Default
not set

Minimum numeric value. The number step buttons clamp to this value; native validation also uses it.

step

RefOrValue<number | string>
Default
1 for step buttons

Positive numeric increment. Invalid or non-positive values fall back to 1 for the step buttons.

placeholder

RefOrValue<string>
Default
not set

A short input hint shown while empty. Keep a separate visible label.

disabled

RefOrValue<boolean>
Default
false

Disables interaction. Use a bound boolean, for example :disabled="isLocked".

icon

RefOrValue<string>
Default
not set

Registered SVG icon name. In browser apps, include the icon in the resolver passed to defineIconComponents.

iconEnd

RefOrValue<string>
Default
not set

Trailing registered SVG icon. Keep the field label visible; an icon is not a replacement for its accessible name.

Composition

No slots. Input events remain native; model is the two-way value contract. Register defineFormInputField and defineIconComponents when using icons.