PixelCluster

Horizontal wrap container for clustering inline items (chips, tags, actions) with consistent gap, alignment, and justification.

Flex row with wrap and configurable stack gap token
Surface-aware transitions
Polymorphic via as to render as any intrinsic element (in Angular, the element you put pxlCluster on)
Align and justify props mirror flexbox semantics

Status: stable
Category: layout
Since: v1.6.0

API

import { PixelCluster } from '@pxlkit/ui-kit';

Prop	Type	Default	Description
`gap`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 \| 12 \| 16`	`4`	Gap token (`stackGap`).
`align`	`'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'`	`'center'`	Cross-axis alignment.
`justify`	`'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'`	—	Main-axis distribution.
`as`	`keyof React.JSX.IntrinsicElements`	—	Element to render.
`surface`	`'pixel' \| 'linear'`	—	Surface override; defaults to the nearest provider.

Also takes the native attributes and event handlers of <div> (HTMLAttributes<HTMLDivElement>).

ref points to <div>.

WCAG target: 2.1 AA

polymorphic-wrap-container

Polymorphic wrap container; inherits semantics from as. Defaults to <div> with no implicit role.

Usage

import React from 'react';
import { PixelCluster } from '@pxlkit/ui-kit';

function Chip({ children }: { children: React.ReactNode }) {
  return (
    <span className="rounded border border-retro-border px-2 py-1 text-xs text-retro-text">
      {children}
    </span>
  );
}

export function Default() {
  return (
    <PixelCluster>
      <Chip>react</Chip>
      <Chip>typescript</Chip>
      <Chip>tailwind</Chip>
      <Chip>next</Chip>
      <Chip>vite</Chip>
    </PixelCluster>
  );
}

Examples

Default

import React from 'react';
import { PixelCluster } from '@pxlkit/ui-kit';

function Chip({ children }: { children: React.ReactNode }) {
  return (
    <span className="rounded border border-retro-border px-2 py-1 text-xs text-retro-text">
      {children}
    </span>
  );
}

export function Default() {
  return (
    <PixelCluster>
      <Chip>react</Chip>
      <Chip>typescript</Chip>
      <Chip>tailwind</Chip>
      <Chip>next</Chip>
      <Chip>vite</Chip>
    </PixelCluster>
  );
}

Justified

import React from 'react';
import { PixelCluster } from '@pxlkit/ui-kit';

function Chip({ children }: { children: React.ReactNode }) {
  return (
    <span className="rounded border border-retro-border px-2 py-1 text-xs text-retro-text">
      {children}
    </span>
  );
}

export function Justified() {
  return (
    <PixelCluster justify="between" gap={6}>
      <Chip>left</Chip>
      <Chip>middle</Chip>
      <Chip>right</Chip>
    </PixelCluster>
  );
}

Pixel Surface

import React from 'react';
import { PixelCluster } from '@pxlkit/ui-kit';

function Chip({ children }: { children: React.ReactNode }) {
  return (
    <span className="rounded border border-retro-border px-2 py-1 text-xs text-retro-text">
      {children}
    </span>
  );
}

export function PixelSurface() {
  return (
    <PixelCluster surface="pixel" gap={3}>
      <Chip>alpha</Chip>
      <Chip>beta</Chip>
      <Chip>gamma</Chip>
    </PixelCluster>
  );
}

Related