Input Group

Input Group

Overview: The Input Group component organizes multiple related input options under a shared label and contextual messaging. It provides structural hierarchy, grouping semantics, and shared context for checkboxes, radio buttons, or switches, ensuring clarity, accessibility, and consistent layout across forms and settings interfaces.

---

Usage Guidelines:

Use Input Group when multiple input options are logically related and should be presented as a single unit.

When to use

• Groups of radio buttons (required for mutual exclusivity)

• Checkbox lists that share a common label or description

• Switch lists under a shared setting or category

• Any input set requiring shared helper or error messaging

When not to use

• Single, standalone input options (use Input Option instead)

• Unrelated inputs that do not share meaning or validation

Best practices

• Always provide a clear group label

• Use supporting text to clarify intent or constraints

• Keep input types consistent within a group

• Apply error states at the group level when validation fails

---

Component Properties:

label (string)

Purpose: Provides a shared title for the input group. Usage: Describe the purpose of the grouped options. Context: Required for accessibility when grouping radio buttons.

---

helper-text (string)

Purpose: Provides additional context or instructions for the group. Usage: Explain how selections affect behavior or outcomes. Context: Optional but recommended for complex choices.

---

has-error (boolean)

Purpose: Indicates whether the group is in an error state. Usage:

• true → group displays error styling and messaging

• false → default appearance Context: Error styling should cascade to nested inputs using alert style where applicable.

---

Appearance Modes:

Supports the following appearance layers through composition:

theme

• Inherited by all nested input components

• Supports light and dark themes

• Maintains consistent contrast across group content

---

size

• Determined by nested input components (sm, base, lg)

• Input Group spacing adjusts automatically to match input size

---

style

• Group itself is neutral

• Semantic styles (cta, alert, grey) are applied at the nested input level

• alert is reserved for error states only

---

status

• Input Group does not define interaction states

• Interaction feedback is handled by nested inputs

ℹ️ Input Group is a structural component and does not override visual states of child inputs.

---

Nested Components:

• Input Option: Primary child component used to render each selectable item.

• Checkbox: Used for independent multi-select options.

• Radio Button: Used for mutually exclusive selections within the group.

• Switch: Used for on/off settings lists.

• Label: Group-level label and per-option labels.

---

♿ Accessibility Considerations:

• Semantic grouping:

  • Implemented using <fieldset> and <legend> semantics

  • Ensures assistive technologies understand relationships between inputs

• Keyboard navigation:

  • Tab enters and exits the group

  • Arrow keys navigate radio button groups

  • Space toggles selected inputs

• Screen reader support:

  • Group label announced before options

  • Error messages announced when present

  • Proper association between group, options, and helper text

• Error handling:

  • When invalid, group uses aria-invalid="true"

  • Error text linked via aria-describedby

---

🧠 Developer Notes:

• Input Group is a layout and semantic wrapper, not an input itself

• Validation logic should live at the group level for radios and checkbox sets

• When has-error = true:

  • Display group-level error messaging

  • Apply alert style to nested Checkbox and Radio Button components

• Maintain consistent selector positioning within a group

• Avoid mixing input types unless explicitly designed

---

Known Issues:

No known issues.

---

Reference Links:

• WCAG 2.1 – Grouped Form Controls

• ARIA Authoring Practices – Fieldset & Legend

• Dev Launchers Design Tokens (Spacing, Typography, Color)