PixelGrid

Surface-aware CSS grid container with responsive column maps, asymmetric gaps, and auto-fit/auto-fill modes.

  • Numeric or responsive column spec (base/sm/md/lg/xl)
  • Asymmetric colGap/rowGap via stack-gap tokens
  • autoFit / autoFill with configurable minColWidth
  • Polymorphic via as (in Angular, the element you put pxlGrid on); inherits semantics from rendered element
  • Surface-aware transition classes
Status
stable
Category
layout
Since
v1.6.0

API

import { PixelGrid } from '@pxlkit/ui-kit';
PropTypeDefaultDescription
cols1 | 2 | 3 | 4 | 5 | 6 | 12 | GridResponsiveColumns—Column count, or a count per breakpoint ({ base: 1, md: 3 }); ignored with autoFit / autoFill.
rows1 | 2 | 3 | 4 | 5 | 6—Row count.
gap0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 164Gap token (stackGap) between rows and columns.
colGap0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16—Gap between columns; with rowGap, it replaces gap.
rowGap0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16—Gap between rows; with colGap, it replaces gap.
autoFitbooleanfalseAs many columns as fit, empty tracks collapsed.
autoFillbooleanfalseAs many columns as fit, empty tracks kept.
minColWidthstring'16rem'Narrowest column with autoFit / autoFill (any CSS length).
align'start' | 'center' | 'end' | 'stretch'—Block-axis alignment of the items.
justify'start' | 'center' | 'end' | 'stretch'—Inline-axis alignment of the items.
askeyof 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>.

Accessibility

WCAG target: 2.1 AA

Renders as <div> by default; inherits semantics from the element provided via as (e.g. ul, section). Authors are responsible for the semantic role of grid children.

Usage

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

function Cell({ children }: { children: React.ReactNode }) {
  return (
    <div className="border border-retro-border bg-retro-surface p-3 text-sm text-retro-text">
      {children}
    </div>
  );
}

export function Default() {
  return (
    <PixelGrid cols={3} gap={4}>
      <Cell>One</Cell>
      <Cell>Two</Cell>
      <Cell>Three</Cell>
      <Cell>Four</Cell>
      <Cell>Five</Cell>
      <Cell>Six</Cell>
    </PixelGrid>
  );
}

Examples

Default

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

function Cell({ children }: { children: React.ReactNode }) {
  return (
    <div className="border border-retro-border bg-retro-surface p-3 text-sm text-retro-text">
      {children}
    </div>
  );
}

export function Default() {
  return (
    <PixelGrid cols={3} gap={4}>
      <Cell>One</Cell>
      <Cell>Two</Cell>
      <Cell>Three</Cell>
      <Cell>Four</Cell>
      <Cell>Five</Cell>
      <Cell>Six</Cell>
    </PixelGrid>
  );
}

Responsive Columns

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

function Cell({ children }: { children: React.ReactNode }) {
  return (
    <div className="border border-retro-border bg-retro-surface p-3 text-sm text-retro-text">
      {children}
    </div>
  );
}

export function Responsive() {
  return (
    <PixelGrid cols={{ base: 1, sm: 2, md: 3, lg: 4 }} gap={4}>
      <Cell>1</Cell>
      <Cell>2</Cell>
      <Cell>3</Cell>
      <Cell>4</Cell>
    </PixelGrid>
  );
}

Auto Fit

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

function Cell({ children }: { children: React.ReactNode }) {
  return (
    <div className="border border-retro-border bg-retro-surface p-3 text-sm text-retro-text">
      {children}
    </div>
  );
}

export function AutoFit() {
  return (
    <PixelGrid autoFit minColWidth="12rem" gap={4}>
      <Cell>Auto A</Cell>
      <Cell>Auto B</Cell>
      <Cell>Auto C</Cell>
      <Cell>Auto D</Cell>
    </PixelGrid>
  );
}

Asymmetric Gaps

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

function Cell({ children }: { children: React.ReactNode }) {
  return (
    <div className="border border-retro-border bg-retro-surface p-3 text-sm text-retro-text">
      {children}
    </div>
  );
}

export function AsymmetricGaps() {
  return (
    <PixelGrid cols={2} colGap={8} rowGap={2}>
      <Cell>A</Cell>
      <Cell>B</Cell>
      <Cell>C</Cell>
      <Cell>D</Cell>
    </PixelGrid>
  );
}

Related