Input Group
FreeSemantic fieldset wrapper for grouping related form fields, with vertical/horizontal layout, bordered or filled variants, fused (seamless) edges and an optional collapsible toggle.
</>sv-group groupfieldsetlayout
import { SvGroupComponent } from '@styloviz/forms';Demo & usage
Basic usage
Usage example — open the gallery for the full interactive demo.
An interactive demo for this component lives in the gallery.
Open live demoMore examples
Collapsible filled section
example.htmlAngular
3 lines
<sv-group label="Advanced" variant="filled" [collapsible]="true" [(collapsed)]="advClosed"> <sv-toggle-switch label="Beta features" [(checked)]="beta" /> </sv-group>
When to use
- Grouping related fields into a labelled section within a larger form.
- You want a semantic fieldset/legend with consistent spacing and optional collapse.
- For unrelated page regions use a Card or layout container instead.
Async states
None — this component has nothing to load, so it has no loading, empty or error state to drive.
Inputs
| Name | Type | Default | Description |
|---|---|---|---|
| label | string | '' | Section label shown above children. |
| description | string | '' | Optional description text below the label. |
| orientation | GroupOrientation | 'vertical' | Layout direction of children. |
| variant | GroupVariant | 'default' | Visual style variant. |
| gap | GroupGap | 'md' | Gap between children (ignored when fused=true). |
| fused | boolean | false | Fuse children edge-to-edge — removes gap and unifies border-radius. Use for button groups, input addons and toolbars. |
| divide | boolean | false | Add dividing lines between children. Direction matches orientation (divide-y vertical, divide-x horizontal). |
| collapsible | boolean | false | Whether the group is collapsible. |
| collapsed | boolean | false | Desired collapsed state (requires `collapsible=true`). |
| errorMessage | string | '' | A validation message about the group as a whole — "Select at least one option", "These dates overlap". Rendered in an `role="alert"` slot, pointed at by the container's `aria-describedby`, and paired with `aria-invalid` on the `role="group"`. **There is deliberately no `serverError` here**, unlike every field control in the kit. `createFieldError` self-expires a server rejection against the value it was reported about; a group owns no value and cannot see its children change, so the anchor could never move. A self-expiring error that never expires is worse than not offering one — a group-level rejection from the server goes here, and the host clears it when it re-validates. |
| errorCount | number | 0 | How many fields inside this group are currently invalid. Rendered as a badge on the header **while the group is collapsed**, which is the only time it tells the user something they cannot already see. Expanded, the errors are on screen and a second count beside the legend is noise. The host owns this number: the group projects arbitrary content and has no business reaching into it to count `aria-invalid`. |
| expandOnError | boolean | true | Never leave an error hidden behind a collapsed header. |
Outputs
| Event | Payload type | Description |
|---|---|---|
| collapsedChange | boolean | The group's collapsed state changed. Always carries the **real** state, including when that is not the state that was asked for: a refused collapse emits `false`, and an auto-expand emits `false` too, so a host mirroring `collapsed` is never left out of sync with what is on screen. |
Customization & theming
- Set `orientation` (vertical/horizontal) and `gap`, then pick a `variant` (default, bordered, filled).
- Use `fused` to merge adjacent control edges or `divide` to add separators between fields.
- Make the section `collapsible` with a two-way `[(collapsed)]` state and a heading `label` / `description`.
Best practices
- Do: Give every group a meaningful `label` — it names the group for assistive tech.
- Do: Use `collapsible` to hide advanced/optional sections by default.
- Don't: Don't nest groups deeply; one level of grouping keeps forms scannable.
Accessibility
- Renders a `role="group"` named via `aria-labelledby` → the heading `label`, so the group is announced for its controls.
- Collapsible groups expose `aria-expanded` / `aria-controls` on the toggle and hide the content region when collapsed.
- Group-level validation ("Select at least one") goes in `errorMessage`: a `role="alert"` slot, with `aria-invalid` and `aria-describedby` on the group container, which also becomes programmatically focusable (`tabindex="-1"`) while invalid so an error summary can reach it.
- Pass `errorCount` (the number of invalid fields inside). While the group is collapsed it shows as a badge with a full sr-only sentence ("3 fields need attention"), named by both the container and the collapse toggle. With `expandOnError` (default on) a programmatic collapse over an error is refused and a collapsed group re-opens when an error appears; a collapse the user asks for is still honoured.
- Projected fields keep their own native labels and focus order; ids are generated per instance.
Feedback on Input Group
Spotted a gap in this page, or something that didn't work as described? Comments are GitHub Discussions in the public styloviz/community repo, so posting needs a GitHub account.