An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:InputGroup authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-27 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/InputGroup/InputGroup.test.tsx, packages/core/src/InputGroup/tests/InputGroupAudit.a11y.chromium.spec.ts, ] modules: [] families: [family:input-fields] design_specs: [design:reduced-motion] architecture: [ architecture:component-size-cascade, architecture:component-theming-surface, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-038, spec:AST-085, spec:AST-102]
InputGroup component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | None changes. InputGroup takes label, isLabelHidden, description, isOptional, isRequired, isDisabled, size, status, labelTooltip, and input and addon children. |
| Behavior | One Field-labelled role="group" row at the shared element height that joins admitted inputs, InputGroupText addons, and Button addons into one connected shape, and gives each grouped input the group's name and description. |
| End-user impact | People see a prefix, input, and suffix as one field, and screen-reader users hear the group label with each input's own label. A disabled group disables its inputs and Button addons together. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior; no API or DOM change and no changed prop value. The row holds a fixed height, Button addons scale under reduced motion, and the row accepts root styling against FR10's scope; all are listed under Current-state impact. |
| Review checks | Reject a grouped input that loses the group label or description, inner corners that round, a disabled group whose compatible children stay operable, or an internal input button reshaped as an addon. |
| Governing rules | family:input-fields FR3, AV3; architecture:component-size-cascade INV3–INV8; spec:AST-085 FR7; spec:AST-038 FR7, FR8; spec:AST-102 FR4; design:reduced-motion DR1. |
This table is a review projection; the body below is authoritative.
Intent
InputGroup joins an input with prefix and suffix addons into one connected
row, as family:input-fields assigns: it owns the row height, the connected
outer shape, edge alignment, and the group's label and supporting text.
Consumer usage lives in InputGroup.doc.mjs.
Compatibility and migration
- Released default preserved:
yes;size="md", label visible, not disabled - Compatibility class: records shipped behavior; no public prop, default, export, or DOM change
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The group Field (label, description, optional or required marker, label
tooltip, detached status message) and the
role="group"row. - The row height and the size it provides to descendants up to the next layer boundary.
- The group context that tells admitted children they are grouped and which label and description ids to compose.
- Connected geometry for direct Button addons.
- The
input-grouptarget.
Does not own / non-goals
- Each grouped input's own adaptation (hidden inner label, no nested Field,
grouped corners, status icon handling) — owned by that input under
family:input-fieldsFR3. - The text addon — owned by
component:InputGroupText(this lane). - Which inputs are admitted — decided per component under
family:input-fieldsFR3; membership alone does not admit one. - Disabling caller-owned controls that do not read the group — not provided.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Size | sm, md, lg |
Row height and default size for children. | Always. | Inherited size, else md |
family:input-fields |
Stable | TypeScript rejects other values. |
| Status | error, warning, success, optional message |
Group validation state. | Always; the message is detached. | none | component:InputGroup |
Stable | TypeScript rejects other types. |
| Disabled | off, on | Disables the group and its compatible children. | Always. | off | component:InputGroup |
Stable | Not applicable. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | InputGroup renders one Field in group-label mode with label (visible unless isLabelHidden), description, the optional or required marker, labelTooltip, and status as a detached message. Inside it, the row is one element with role="group", aria-labelledby set to the label, and aria-describedby set to the description and status message ids that exist. |
family:input-fields FR3; current tests |
| FR2 | Grouped inputs receive the label id and description ids through context. Each admitted input is named by the group label plus its own label and described by the group's description and status plus its own. | family:input-fields FR3; current tests |
| FR3 | The row is inline-flex, stretched, and transparent; its height is the shared element height for its size, as a minimum that grows with a set text size under spec:AST-102 FR4. Implementation gap: the height is fixed at that size. It provides its resolved size to descendants up to the next layer boundary (spec:AST-038 FR7, FR8): explicit size, then the nearest outer provider, then md. |
family:input-fields FR3; architecture:component-size-cascade; current source |
| FR4 | Direct Button addons join the shape: no inner corner rounding toward a neighbour, full row height, and their keyboard focus ring raised above the adjacent member. Buttons deeper inside a grouped input (clear, calendar, disclosure), and a Button addon wrapped in a Tooltip or HoverCard (not a direct child), keep their own shape. A following popover, template, or dialog element does not count as a neighbour. Addons are component:Buttons outside a ButtonGroup, so their press scale MUST NOT apply under reduced motion (design:reduced-motion DR1). Implementation gap: it still applies under reduced motion. |
Current source; design:reduced-motion DR1 |
| FR5 | The role="group" row inside the Field box carries astryx-input-group and reflects data-size and data-status. ref, data-testid, and other DOM props reach the row. InputGroup composes Field, so family:input-fields FR10 forbids root xstyle, className, and style. Implementation gap: they are accepted and reach the row. |
architecture:component-theming-surface; family:input-fields FR10; current tests |
| FR6 | The group is disabled when its own isDisabled or an enclosing InputGroup's is true. A disabled group sets aria-disabled="true" on the row, dims it to half opacity with the default cursor, passes the disabled state to the group Field, and disables every compatible child (TextInput, NumberInput, Selector, MultiSelector, DateInput, TimeInput, Typeahead, and Button addons) and nested group up to the next layer boundary; each child then follows its own disabled contract. A child or nested group that disables itself stays disabled when the group is enabled. Caller-owned controls that do not read the group are unaffected. |
spec:AST-085 FR7; spec:AST-038 FR7, FR8; current tests |
Allowed variation
- AV1 — Members. Any admitted input, InputGroupText, Button, and Button-triggered controls may appear in any order.
- AV2 — Status paint. A theme may paint the group from
data-status; core paints no group border for it.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Prefix text + TextInput | One row; outer corners only; input named by group and own label. | Size. |
| Input + Button suffix | Button full height, square toward the input. | Variant. |
| With description and status | Group and inputs described by both; message detached below. | — |
| Hidden label | Label visually hidden; still names the group. | — |
Transformation and precedence order
- ORD1 — Size. Explicit
size, then outer provider, thenmd; a grouped input's own explicitsizestill wins for that input. - ORD2 — Description. Group description, then group status message.
Performance and resources
- PR1 — No measurement. Geometry comes from CSS selectors; InputGroup adds no observer or listener.
Accessibility contract
- AR1 — Group name.
role="group"labelled by the visible or hidden label (FR1). - AR2 — Input names. Each admitted input combines the group label with its own label, so its purpose stays specific (FR2).
- AR3 — Focus. A focused member is raised above its neighbours so its focus presentation is not covered.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Label | Group label above the row, or hidden. | Current source | Prominent | FR1 |
| Prefix addon | Text or Button before the input, joined to it. | Current source | Supporting | FR4 |
| Input | The admitted input, filling remaining width. | Current source | Prominent | FR2 |
| Suffix addon | Text or Button after the input, joined to it. | Current source | Supporting | FR4 |
design:reduced-motion governs the Button addons' press scale (FR4); no other
design record governs InputGroup. The row carries input-group; the
consumer anatomy names no row part, so this record carries no anatomy-theming
map.
Family and system relationships
family:input-fieldsassigns InputGroup the row height, connected surface, edge alignment, and group focus; admission stays with each input.component:InputGroupTextsupplies the text addon.component:Buttonapplies FR4's addon geometry from the group context.architecture:component-size-cascadeowns size inheritance (FR3).
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | InputGroup.test.tsx label, description, status, hidden-label, marker and label-tooltip cases; InputGroupAudit.a11y.chromium.spec.ts label, hidden-label, description and status cases |
Visible and hidden label; optional and required marker; label tooltip; description and status | A missing group name or description, a missing marker or label tooltip, a hidden label that shows, or a status message missing from the description or not below the row fails. | audit:InputGroup/accessibility |
| FR2, AR2 | InputGroup.test.tsx grouped-input naming cases and the grouped DateInput semantics case |
TextInput, NumberInput, DateInput, Typeahead, Selector, MultiSelector | A grouped input that loses the group or its own label fails. | audit:InputGroup/accessibility |
| FR4 | InputGroupAudit.a11y.chromium.spec.ts joined-corner and member-height checks |
Button addon combinations; prefix and suffix; right-to-left | A member that rounds toward a neighbour, an outer corner that is square where it should round, or a member shorter than the row fails. Evidence gap: no test covers a wrapped addon or the reduced-motion press; component:Button verifies its own side. |
audit:InputGroup/layout |
| FR5 | InputGroup.test.tsx row-reflection and data-testid cases |
Root; size and status |
A missing astryx-input-group target, data-size or data-status, a ref that does not reach the row, or a dropped test id fails. Evidence gap: no test asserts className, style, or xstyle. |
audit:InputGroup/theming |
| FR6 | InputGroup.test.tsx disabled-propagation cases |
Every compatible input and Button addon; nested groups; re-enabled group with an explicitly disabled child | A child that stays operable in a disabled group, a nested group that opts out, or a re-enabled explicitly disabled child fails. | audit:InputGroup/behavior |
| FR3, ORD1 | InputGroup.test.tsx size-precedence case; InputGroupAudit.a11y.chromium.spec.ts row-height check |
Explicit size, outer provider, and no size given; sm, md, lg rows |
A size that ignores the prop or the provider, an input that does not take the group's size, or rows that do not grow from sm to lg fails. Evidence gap: no test asserts growth with a set text size (FR3's gap). |
audit:InputGroup/layout |
| FR6 (paint), ORD2, AR3 | InputGroupAudit.a11y.chromium.spec.ts disabled, description and focus cases; InputGroup.test.tsx description-order case |
Disabled group; description then status; keyboard focus on each of two adjacent members | A disabled row that is not half opacity with the arrow cursor, a status message before the description, or a focused member that is not above every unfocused member fails. | audit:InputGroup/behavior |
| PR1 | Evidence gap: no test asserts the absence of observers | — | — | audit:InputGroup/behavior |
Current-state impact
- Fixed height (FR3). The row holds the fixed shared element height instead
of growing with a set text size, against
spec:AST-102FR4. - Addon press under reduced motion (FR4). A Button addon scales to 0.98 on a
press when the person prefers reduced motion, as
component:ButtonFR15 records, againstdesign:reduced-motionDR1. - Root styling (FR5). InputGroup accepts root
className,style, andxstyleon its row, against the scope offamily:input-fieldsFR10. FR10 item 3 names InputGroup as the caller's styling surface, and the family coverage testField/fieldInputFamily.test.tsxleaves InputGroup out of its field inputs, so this gap may close by clarifying FR10 rather than by changing code.
Decision log
No component-local decision. InputGroup applies family:input-fields.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.