Cluster
Horizontal flex flow with wrap and token-bound gap. Use for tag lists, button rows, breadcrumbs, and any group of equally-weighted inline items.
Tag chips (wrap on overflow)
Action bar — pushed right with justify="end"
Centered row — justify="center"
Installation
pnpm dlx @hex-core/cli add clusterAction bar
Right-aligned buttons inside a panel footer.
<Cluster gap="sm" justify="end">
<Button variant="ghost">Cancel</Button>
<Button>Save</Button>
</Cluster>Variant values
gapGap between items, bound to `--gap-*` tokens (applies to row + column gaps when wrapping).xssmmdlgxl| Value | Description |
|---|---|
xs | 0.25rem — barely-there spacing. |
sm | 0.5rem — tight chip group. |
mddefault | 1rem — default; standard rhythm. |
lg | 1.5rem — generous separation. |
xl | 2rem — section-scale spacing. |
alignCross-axis alignment (CSS `align-items`).startcenterendstretchbaseline| Value | Description |
|---|---|
start | Items align to top of row. |
centerdefault | Default — items center vertically in the row. |
end | Items align to bottom of row. |
stretch | Items fill row height — use for wrap layouts of equal-height cards. |
baseline | Text-baselines align across mixed-size siblings. |
justifyMain-axis distribution (CSS `justify-content`).startcenterendbetween| Value | Description |
|---|---|
startdefault | Default — items pack to start of row. |
center | Items center horizontally. |
end | Items pack to end of row. |
between | First item flush left, last flush right, even distribution. |
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
gap | "xs" | "sm" | "md" | "lg" | "xl" | md | Gap between items, bound to `--gap-*` tokens. Applies to both row and column gaps when wrapping. |
align | "start" | "center" | "end" | "stretch" | "baseline" | center | Cross-axis alignment (CSS `align-items`). `baseline` aligns text-baselines for mixed-size siblings; `stretch` makes items fill row height (useful for wrap-card layouts). |
justify | "start" | "center" | "end" | "between" | start | Main-axis distribution (CSS `justify-content`). |
AI Guidance
When to use
Use for any horizontal row of items that should wrap when space runs out: tag clouds, breadcrumbs, button rows, social-link icon strips, inline metadata badges. Pick `Cluster` over `flex` when you want predictable wrap + gap behavior.
When not to use
Don't use for two-element rows where you need precise positional control (left/right) — use `Stack` rotated or a flex with `justify-between` directly. Don't use for grid-aligned layouts where columns must line up across rows — use `Grid`.
Common mistakes
- Forgetting that `Cluster` wraps — adding `flex-nowrap` defeats the purpose; if you don't want wrap, use a flex row or `Stack` rotated
- Setting `align="baseline"` for icon+text rows where the icon's bbox doesn't have a baseline — use `center` instead
- Reaching for `Cluster` for tabular alignment — use `Grid` or a real `<table>` when columns must line up
Accessibility
Cluster is presentational. Lists of navigational items should be wrapped in `<nav>` (and ideally `<ul>` / `<li>`). Lists of tags can use a list element for screen-reader semantics; the visual wrap is independent.
Token budget: 250