Cluster

Flex-wrap primitive for variable-width children like tags, chips, and buttons with token gap spacing.

Components

Cluster

layout

static

<arc-cluster>

Overview

Cluster is a flex-wrap layout primitive designed for groups of variable-width inline elements — tags, chips, badges, buttons, or any set of items that should flow naturally across the available width and wrap to the next line when space runs out. It is the horizontal-flow counterpart to Stack (vertical spacing) and the wrapping counterpart to a simple flexbox row. The component applies `display: flex`, `flex-wrap: wrap`, and token-based gap spacing, with configurable `align` and `justify` props that map to `align-items` and `justify-content`. This covers the full range of common inline-group patterns: left-aligned tag lists, centered button groups, space-between navigation items, and everything in between. Use Cluster whenever you have a set of inline elements that should wrap naturally. For fixed-column grids, use DashboardGrid or AspectGrid. For vertical stacking, use Stack. For a single row that should never wrap, use a plain flex container with `flex-wrap: nowrap`.

Guidelines

When to use

Use for tag lists, chip groups, and badge collections
Use for button groups that should wrap on narrow screens
Use gap="sm" for dense tag/chip groups; gap="md" for button groups
Use justify="space-between" for navigation-style layouts with space between items
Combine with Inset for padded containers of clustered items

When not to use

Do not use Cluster for vertical stacking — use Stack instead
Do not use Cluster for fixed-column grids — use DashboardGrid or AspectGrid
Do not set large gap values on dense tag lists — it creates excessive whitespace
Do not nest Cluster inside Cluster unless you intentionally want compound wrapping groups
Do not use Cluster for single items — it adds unnecessary wrapper overhead

Features

Flex-wrap layout for natural inline-flow wrapping
Design-token-based gap spacing (xs, sm, md, lg) for consistent rhythm
Configurable alignment via `align` prop (start, center, end)
Configurable justification via `justify` prop (start, center, end, space-between, space-around)
Handles variable-width children gracefully — no fixed column assumptions
Lightweight wrapper with zero JavaScript overhead
CSS part: `cluster` for targeted ::part() styling

Preview

Design Engineering Product Marketing Sales Support Research Operations

Usage

<arc-cluster gap="sm" align="center" justify="start">
  <arc-tag>Design</arc-tag>
  <arc-tag>Engineering</arc-tag>
  <arc-tag>Product</arc-tag>
  <arc-tag>Marketing</arc-tag>
  <arc-tag>Sales</arc-tag>
  <arc-tag>Support</arc-tag>
</arc-cluster>

import { Cluster, Tag } from '@arclux/arc-ui-react';

function TagList() {
  const tags = ['Design', 'Engineering', 'Product', 'Marketing', 'Sales', 'Support'];

  return (
    <Cluster gap="sm" align="center" justify="start">
      {tags.map(tag => <Tag key={tag}>{tag}</Tag>)}
    </Cluster>
  );
}

<script setup>
import { Cluster, Tag } from '@arclux/arc-ui-vue';

const tags = ['Design', 'Engineering', 'Product', 'Marketing', 'Sales', 'Support'];
</script>

<template>
  <Cluster gap="sm" align="center" justify="start">
    <Tag v-for="tag in tags" :key="tag">{{ tag }}</Tag>
  </Cluster>
</template>

<script>
  import { Cluster, Tag } from '@arclux/arc-ui-svelte';

  const tags = ['Design', 'Engineering', 'Product', 'Marketing', 'Sales', 'Support'];
</script>

<Cluster gap="sm" align="center" justify="start">
  {#each tags as tag}
    <Tag>{tag}</Tag>
  {/each}
</Cluster>

import { Component } from '@angular/core';
import { Cluster, Tag } from '@arclux/arc-ui-angular';

@Component({
  imports: [Cluster, Tag],
  template: `
    <arc-cluster gap="sm" align="center" justify="start">
      @for (tag of tags; track tag) {
        <arc-tag>{{ tag }}</arc-tag>
      }
    </arc-cluster>
  `,
})
export class TagListComponent {
  tags = ['Design', 'Engineering', 'Product', 'Marketing', 'Sales', 'Support'];
}

import { For } from 'solid-js';
import { Cluster, Tag } from '@arclux/arc-ui-solid';

function TagList() {
  const tags = ['Design', 'Engineering', 'Product', 'Marketing', 'Sales', 'Support'];

  return (
    <Cluster gap="sm" align="center" justify="start">
      <For each={tags}>{tag => <Tag>{tag}</Tag>}</For>
    </Cluster>
  );
}

import { Cluster, Tag } from '@arclux/arc-ui-preact';

function TagList() {
  const tags = ['Design', 'Engineering', 'Product', 'Marketing', 'Sales', 'Support'];

  return (
    <Cluster gap="sm" align="center" justify="start">
      {tags.map(tag => <Tag key={tag}>{tag}</Tag>)}
    </Cluster>
  );
}

<!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-cluster — requires cluster.css + base.css (or arc-ui.css) -->
<div class="arc-cluster">
  Cluster
</div>

<!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-cluster — self-contained, no external CSS needed -->
<div class="arc-cluster" style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center">
  Cluster
</div>

API

gap 'xs' | 'sm' | 'md' | 'lg' | 'xl' ='sm': Spacing between items, mapped to design system spacing tokens. Use sm for dense tag groups, md for button groups.
align 'start' | 'center' | 'end' ='center': Vertical alignment of items within each row (maps to align-items).
justify 'start' | 'center' | 'end' | 'space-between' | 'space-around' ='start': Horizontal distribution of items (maps to justify-content). Use "space-between" for navigation-style spacing.

Cluster

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

See Also

Docs

Project

Arclight