Skip to main content

Field

A generic headless form-field container that provides shared ARIA context, coordinated IDs, and validation/disabled/required/read-only state for any form control. Does not own validation logic — invalid is a controlled prop driven by external validators (Zod, etc.).

Live Demo​

JavaScript
<Field.Root className='field-demo' invalid>
<Field.Label className='field-label'>Email</Field.Label>
<input className='field-input' placeholder='user@example.com' />
<Field.Description className='field-description'>
  We'll never share your email.
</Field.Description>
<Field.ErrorMessage className='field-error'>
  Please enter a valid email address.
</Field.ErrorMessage>
</Field.Root>

Features​

  • ✅ Coordinated ARIA IDs for label, description, error, and field elements
  • ✅ Validation, disabled, required, and read-only state propagation
  • ✅ Conditional error message rendering (only when invalid)
  • ✅ Polymorphic as prop on all compound parts
  • ✅ Render props support for children function with field state
  • ✅ Works with any form control (Input, Switch, Checkbox, Select, etc.)

Import​

import { Field } from '@turkish-technology/spar';

Field and Field.Root refer to the same component — the difference is only notation style:

// Dot notation
<Field.Root>
<Field.Label />
<Field.Description />
<Field.ErrorMessage />
</Field.Root>;

// Named import style
import {
Field,
FieldLabel,
FieldDescription,
FieldErrorMessage,
} from '@turkish-technology/spar';

<Field>
<FieldLabel />
<FieldDescription />
<FieldErrorMessage />
</Field>;

Anatomy​

We'll never share your email.
Parts
RootContext provider managing IDs and state
LabelAccessible label with auto-linked htmlFor
DescriptionHelper text linked via aria-describedby
ErrorMessageError announcement with role="alert" (only when invalid)

Structure​

<Field.Root>
<Field.Label />
{/* your form control here */}
<Field.Description />
<Field.ErrorMessage />
</Field.Root>

Data Flow:

  • Field.Root: Context provider managing coordinated IDs and form state
  • Field.Label: Accessible <label> auto-linked via htmlFor to the field's control
  • Field.Description: Helper/hint text linked via aria-describedby
  • Field.ErrorMessage: Error text with role="alert", only renders when invalid is true

Code Examples​

Basic Field with Input​

A simple field wrapping a native input with label and description.

function BasicField() {
return (
<Field.Root>
<Field.Label>Username</Field.Label>
<input placeholder="Enter your username" />
<Field.Description>Choose a unique username</Field.Description>
</Field.Root>
);
}

Invalid State with Error Message​

When invalid is set, Field.ErrorMessage renders and gets announced via role="alert".

function InvalidField() {
const [value, setValue] = React.useState('');
const isEmpty = value.trim().length === 0;

return (
<Field.Root invalid={isEmpty} required>
<Field.Label>Email</Field.Label>
<input
type="email"
value={value}
onChange={e => setValue(e.target.value)}
placeholder="user@example.com"
/>
<Field.Description>We'll use this for account recovery</Field.Description>
<Field.ErrorMessage>Email is required</Field.ErrorMessage>
</Field.Root>
);
}

Disabled Field​

Disabled state propagates to all compound children via context.

function DisabledField() {
return (
<Field.Root disabled>
<Field.Label>Account Type</Field.Label>
<input value="Premium" readOnly />
<Field.Description>Contact support to change your plan</Field.Description>
</Field.Root>
);
}

Polymorphic Rendering with as​

Use the as prop to change the rendered element on any part.

function FieldsetField() {
return (
<Field.Root as="fieldset">
<Field.Label as="legend">Preferences</Field.Label>
<label>
<input type="checkbox" /> Receive email notifications
</label>
<label>
<input type="checkbox" /> Receive SMS notifications
</label>
</Field.Root>
);
}

Render Props​

Use a children function to access field state and conditionally render content.

function RenderPropsField() {
return (
<Field.Root invalid required>
{({ invalid, disabled, required, readOnly }) => (
<>
<Field.Label>Password</Field.Label>
<input type="password" placeholder="Enter password" />
{invalid && (
<span style={{ color: 'red' }}>⚠ This field has errors</span>
)}
{required && <span style={{ fontSize: 12 }}>* Required</span>}
</>
)}
</Field.Root>
);
}

Render Props with Dynamic Styling​

Render props let you apply conditional styles based on field state.

function DynamicStyledField() {
const [invalid, setInvalid] = React.useState(false);

return (
<Field.Root invalid={invalid}>
{({ invalid, disabled }) => (
<>
<Field.Label>Full Name</Field.Label>
<input
style={{
borderColor: invalid ? '#d14343' : '#e1e4ea',
opacity: disabled ? 0.5 : 1,
}}
onChange={e => setInvalid(e.target.value.length === 0)}
placeholder="Enter your full name"
/>
<Field.ErrorMessage>Name cannot be empty</Field.ErrorMessage>
</>
)}
</Field.Root>
);
}

Render Props with Custom Badge​

Use render props to show status badges alongside field state.

function BadgeField() {
return (
<Field.Root required readOnly>
{({ required, readOnly }) => (
<div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
<div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
<Field.Label>API Key</Field.Label>
{required && <span className="badge-required">Required</span>}
{readOnly && <span className="badge-readonly">Read-only</span>}
</div>
<input value="sk-abc123..." readOnly />
<Field.Description>Your API key for authentication</Field.Description>
</div>
)}
</Field.Root>
);
}

Combined with useFieldContext Hook​

For components nested deeper than direct children, use the useFieldContext hook.

import { Field, useFieldContext } from '@turkish-technology/spar';

function CustomInput() {
const { fieldId, invalid, disabled } = useFieldContext();
return (
<input
id={fieldId}
disabled={disabled}
aria-invalid={invalid}
style={{ borderColor: invalid ? 'red' : 'gray' }}
/>
);
}

function FieldWithCustomInput() {
return (
<Field.Root invalid>
<Field.Label>Custom Input</Field.Label>
<CustomInput />
<Field.ErrorMessage>Something went wrong</Field.ErrorMessage>
</Field.Root>
);
}

API Reference​

Field / Field.Root​

The root context provider that wraps all compound field parts. Field and Field.Root are the same component. Renders a <div> by default.

Props

NameTypeDefaultDescription
id?stringundefinedBase ID for ARIA relationships. Sub-element IDs are derived from this.
as?React.ElementType'div'Polymorphic element type
ref?React.Ref<T>undefinedRef for the root element
childrenReact.ReactNode | ((props: FieldRenderProps) => ReactNode)-Static content or render function receiving field state
invalid?booleanfalseValidation state propagated to all compound parts
disabled?booleanfalseDisabled state propagated to all compound parts
required?booleanfalseRequired state propagated to all compound parts
optional?booleanfalseOptional state propagated to all compound parts
readOnly?booleanfalseRead-only state propagated to all compound parts
...propsReact.ComponentProps<T>-All standard HTML attributes for the root element

FieldRenderProps (passed to children function)

NameTypeDescription
invalidbooleanWhether the field is in error state
disabledbooleanWhether the field is disabled
requiredbooleanWhether the field is required
optionalbooleanWhether the field is optional
readOnlybooleanWhether the field is read-only

Data Attributes

AttributeValuePurpose
data-invalid"" | undefinedIndicates validation state
data-disabled"" | undefinedIndicates disabled state
data-required"" | undefinedIndicates required state
data-optional"" | undefinedIndicates optional state
data-readonly"" | undefinedIndicates read-only state

Field.Label​

Accessible label auto-linked to the field's control via htmlFor. Renders <label> by default.

Props

NameTypeDefaultDescription
as?React.ElementType'label'Polymorphic element type
childrenReact.ReactNode-Label content
ref?React.Ref<T>undefinedRef for the label element

Auto-set from context:

  • id → ${rootId}-label
  • htmlFor → ${rootId}-field
  • disabled, required, optional, readOnly, invalid mirror the root state

Field.Description​

Helper/hint text linked to the control via aria-describedby. Renders <div> by default.

Props

NameTypeDefaultDescription
as?React.ElementType'div'Polymorphic element type
childrenReact.ReactNode-Description content
ref?React.Ref<T>undefinedRef for the element

Data Attributes

AttributeValuePurpose
data-disabled"" | undefinedIndicates disabled state
data-readonly"" | undefinedIndicates read-only state

Field.ErrorMessage​

Error message that only renders when invalid is true. Uses role="alert" for immediate screen reader announcement.

Props

NameTypeDefaultDescription
as?React.ElementType'div'Polymorphic element type
childrenReact.ReactNode-Error content
ref?React.Ref<T>undefinedRef for the element

Data Attributes

AttributeValuePurpose
role"alert"Announces error to screen readers
data-invalid"" | undefinedIndicates validation state
data-disabled"" | undefinedIndicates disabled state
data-readonly"" | undefinedIndicates read-only state

Accessibility​

FeatureImplementation
Label associationField.Label auto-sets htmlFor matching the field's control
Description linkingField.Description ID used in aria-describedby
Error announcementField.ErrorMessage uses role="alert" (assertive live)
Disabled propagationContext shares disabled to all compound parts
Required propagationContext shares required to all compound parts
Data attributesStyling hooks via data-invalid, data-disabled, etc.