SutraUI.Field (Sutra UI v0.2.0)

View Source

Combine labels, controls, and help text to compose accessible form fields.

Provides two main components:

  • field/1 - Individual field container (label, input, helper text, errors)
  • fieldset/1 - Groups multiple related fields together

Accessibility

This component implements the WAI-ARIA field pattern:

  • Uses role="group" for field container
  • Generates unique IDs for helper text and errors
  • Helper text linked via aria-describedby
  • Error messages linked via aria-describedby and aria-invalid
  • Fieldsets use semantic <fieldset> and <legend> elements

Summary

Functions

field(assigns)

Renders a field container for form inputs.

fieldset(assigns)

Renders a fieldset container for grouping related fields.

Functions

field(assigns)

Renders a field container for form inputs.

Fields automatically manage the layout of labels, inputs, helper text, and error messages. Use the slots to compose the field structure.

Examples

# Basic field with label and input
<.field>
  <:label for="username">Username</:label>
  <:input>
    <input id="username" type="text" placeholder="evilrabbit" />
  </:input>
  <:description id="username-desc">Choose a unique username.</:description>
</.field>

# Horizontal orientation (checkbox/switch pattern)
<.field orientation="horizontal">
  <:input>
    <input id="newsletter" type="checkbox" />
  </:input>
  <:label for="newsletter">Subscribe to newsletter</:label>
</.field>

# Field with error state
<.field invalid>
  <:label for="password">Password</:label>
  <:input>
    <input id="password" type="password" aria-invalid="true" />
  </:input>
  <:error id="password-error">Password must be at least 8 characters</:error>
</.field>

# With section (complex horizontal layout)
<.field orientation="horizontal">
  <:section>
    <:label for="mfa">Multi-factor authentication</:label>
    <:description>Enable MFA for enhanced security</:description>
  </:section>
  <:input>
    <input id="mfa" type="checkbox" role="switch" />
  </:input>
</.field>

Attributes

  • orientation (:string) - Layout orientation - vertical stacks label above input, horizontal aligns side-by-side. Defaults to "vertical". Must be one of "vertical", or "horizontal".
  • invalid (:boolean) - Mark field as invalid (applies error styling). Defaults to false.
  • class (:string) - Additional CSS classes. Defaults to nil.
  • Global attributes are accepted. Additional HTML attributes. Supports all globals plus: ["id", "role"].

Slots

  • label - Label for the input (use 'for' attribute to associate with input). Accepts attributes:
    • for (:string) - Associates label with input.
    • class (:string) - Additional CSS classes.
  • section - Wraps label and description when label sits beside input (for horizontal orientation). Accepts attributes:
    • class (:string) - Additional CSS classes for the section.
  • input (required) - The form input control.
  • description - Helper text (use 'id' attribute and reference with aria-describedby on input). Accepts attributes:
    • id (:string) - ID for aria-describedby reference.
  • error - Error message (use 'id' attribute, reference with aria-describedby, and set aria-invalid on input). Accepts attributes:
    • id (:string) - ID for aria-describedby reference.

fieldset(assigns)

Renders a fieldset container for grouping related fields.

Fieldsets use semantic HTML with <fieldset> and <legend> elements, providing proper accessibility for groups of related form controls.

Examples

# Basic fieldset with multiple fields
<.fieldset>
  <:legend>Profile Information</:legend>
  <:description>This information will be displayed on your profile</:description>
  <:fields>
    <.field>
      <:label for="name">Full name</:label>
      <:input>
        <input id="name" type="text" placeholder="Evil Rabbit" />
      </:input>
    </.field>

    <.field>
      <:label for="email">Email</:label>
      <:input>
        <input id="email" type="email" placeholder="evil@rabbit.com" />
      </:input>
    </.field>
  </:fields>
</.fieldset>

# Disabled fieldset (disables all child inputs)
<.fieldset disabled>
  <:legend>Locked Section</:legend>
  <:fields>
    <.field>
      <:label for="locked">This is disabled</:label>
      <:input>
        <input id="locked" type="text" />
      </:input>
    </.field>
  </:fields>
</.fieldset>

Attributes

  • class (:string) - Additional CSS classes. Defaults to nil.
  • Global attributes are accepted. Additional HTML attributes. Supports all globals plus: ["id", "disabled"].

Slots

  • legend (required) - Heading for the fieldset.
  • description - Description text.
  • fields (required) - Individual field containers or form controls.