Forms

FormField

Wrapper primitive that pairs a single control with its label, description, and error and wires the ARIA association via context.

import { FormField } from '@lostgradient/cinder/form-field';
formwrapper
01

Overview

Wraps an input, label, and helper or error text into a cohesive accessible field unit.

Usage

svelte 
<script lang="ts">
  import FormField from '@lostgradient/cinder/form-field';
  import Input from '@lostgradient/cinder/input';

  let name = $state('');
</script>

<FormField id="full-name" label="Full name">
  <Input id="full-name" bind:value={name} placeholder="Jane Smith" />
</FormField>
Live preview
02

When to use

Use when
  • Composing a one-off field where the input does not own its own label rendering.
  • Forwarding shared required, disabled, and error state to an opted-in child control.
Avoid when
  • Grouping multiple related controls under one heading — use form-section instead.
03

Examples

Basic form field

A form field wrapping an input with label association.

Composed input — context inheritance

Input inside FormField inherits aria-describedby and aria-invalid from context.

Form field with error

Error state wires aria-invalid and aria-describedby on the wrapped control.

04

Props

Props for form-field
NameTypeDefaultDescription
id required text Required stable id — used for <label for>, description, error, and the child control's id via context.
label text Visible label text. Omit only when the child control supplies its own accessible name, such as via aria-label or aria-labelledby.
labelVisible boolean true Whether the label is visibly rendered. Set false to visually hide it while keeping it associated with the control.
description text Helper text rendered below the control; wired into aria-describedby.
error text Validation error; sets aria-invalid="true" on opted-in controls via context.
required boolean false Renders a visual required marker and exposes required: true on the context.
disabled boolean false Propagated to opted-in controls via context. Does not style FormField itself.
children required snippet Control(s) rendered inside the field.