PixelSection

Bordered section with optional uppercase title row, subtitle, and surface-aware container.

Surface-aware borders and typography
Optional title (uppercased via locale) and subtitle row
Configurable container max-width or full-bleed with page gutter
Vertical rhythm token controls spacing between sections

Status: stable
Category: layout
Since: v1.6.0

API

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

Prop	Type	Default	Description
`title`	`string`	—	Title rendered as an uppercase heading row at the top of the section.
`subtitle`	`string`	—	Optional subtitle below the title.
`children` (required)	`React.ReactNode`	—	Section content.
`surface`	`'pixel' \| 'linear'`	—	Surface variant. Falls back to nearest <PxlKitSurface>.
`container`	`'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl' \| '7xl' \| 'prose' \| 'full' \| false`	`'5xl'`	Inner container max-width. Pass `false` to skip the centered container wrapper.
`verticalPadding`	`'none' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'xl'`	Vertical padding token (margin between consecutive sections).
`horizontalGutter`	`0 \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'lg'`	Horizontal gutter token (used only when `container` is `false`).
`bordered`	`boolean`	`false`	Render with surface-aware border + radius chrome. Defaults to false (no chrome).

ref points to its element (HTMLElement).

WCAG target: 2.1 AA

semantic-section

Renders as a semantic <section>. When title is provided it becomes the section heading; consumers may add aria-labelledby externally when needed.

Usage

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

export function Default() {
  return (
    <PixelSection title="Overview" subtitle="Key metrics for this period.">
      <p className="text-sm text-retro-muted">
        Section content goes here. Wrap any layout block.
      </p>
    </PixelSection>
  );
}

Examples

Default

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

export function Default() {
  return (
    <PixelSection title="Overview" subtitle="Key metrics for this period.">
      <p className="text-sm text-retro-muted">
        Section content goes here. Wrap any layout block.
      </p>
    </PixelSection>
  );
}

Without Title

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

export function WithoutTitle() {
  return (
    <PixelSection>
      <p className="text-sm text-retro-muted">A bare section without a title row.</p>
    </PixelSection>
  );
}

Pixel Surface

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

export function PixelSurface() {
  return (
    <PixelSection surface="pixel" title="Pixel Surface" subtitle="8-bit aesthetic.">
      <p className="text-sm text-retro-muted">Renders with the pixel surface tokens.</p>
    </PixelSection>
  );
}

No Container

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

export function NoContainer() {
  return (
    <PixelSection container={false} horizontalGutter="md" title="Full Width">
      <p className="text-sm text-retro-muted">No centered container; uses page gutters.</p>
    </PixelSection>
  );
}

Related