PixelStack

Polymorphic flex container with token-driven gap, direction, alignment, and surface-aware transitions.

Direction toggle between column and row flex layouts
Token-based gap scale via stackGap for consistent rhythm
Alignment and justification helpers including baseline and space variants
Surface-aware transitions
Polymorphic via the as prop to render any intrinsic element (in Angular, the element you put pxlStack on)

Status: stable
Category: layout
Since: v1.6.0

API

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

Prop	Type	Default	Description
`direction`	`'col' \| 'row'`	`'col'`	Main axis.
`gap`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 \| 12 \| 16`	`4`	Gap token (`stackGap`).
`align`	`'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'`	—	Cross-axis alignment.
`justify`	`'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'`	—	Main-axis distribution.
`wrap`	`boolean`	`false`	Wrap onto multiple lines.
`inline`	`boolean`	`false`	`inline-flex` instead of `flex`.
`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-flex-container

Renders as <div> by default; inherits semantics from the as prop when overridden.

Usage

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

export function Default() {
  return (
    <PixelStack gap={4}>
      <div className="text-sm text-retro-muted">First item</div>
      <div className="text-sm text-retro-muted">Second item</div>
      <div className="text-sm text-retro-muted">Third item</div>
    </PixelStack>
  );
}

Examples

Default

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

export function Default() {
  return (
    <PixelStack gap={4}>
      <div className="text-sm text-retro-muted">First item</div>
      <div className="text-sm text-retro-muted">Second item</div>
      <div className="text-sm text-retro-muted">Third item</div>
    </PixelStack>
  );
}

Row

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

export function Row() {
  return (
    <PixelStack direction="row" gap={3} align="center">
      <div className="text-sm text-retro-muted">Left</div>
      <div className="text-sm text-retro-muted">Center</div>
      <div className="text-sm text-retro-muted">Right</div>
    </PixelStack>
  );
}

Space Between

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

export function SpaceBetween() {
  return (
    <PixelStack direction="row" justify="between" align="center">
      <div className="text-sm text-retro-muted">Start</div>
      <div className="text-sm text-retro-muted">End</div>
    </PixelStack>
  );
}

Wrapped

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

export function Wrapped() {
  return (
    <PixelStack direction="row" gap={2} wrap>
      <div className="text-sm text-retro-muted">Tag A</div>
      <div className="text-sm text-retro-muted">Tag B</div>
      <div className="text-sm text-retro-muted">Tag C</div>
      <div className="text-sm text-retro-muted">Tag D</div>
    </PixelStack>
  );
}

Pixel Surface

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

export function PixelSurface() {
  return (
    <PixelStack surface="pixel" gap={4}>
      <div className="text-sm text-retro-muted">Surface-aware item</div>
      <div className="text-sm text-retro-muted">Picks up pixel transition</div>
    </PixelStack>
  );
}

Related