Preview Block

A container component that displays live previews of components in documentation. Shows component boundaries with optional background patterns, perfect for showcasing UI components.

Installation

npm install @kushagradhawan/kookie-blocks

Usage

import { PreviewBlock } from '@kushagradhawan/kookie-blocks';
import { Button } from '@kushagradhawan/kookie-ui';
 
export function Example() {
  return (
    <PreviewBlock>
      <Button>Click me</Button>
    </PreviewBlock>
  );
}

Props

Background Variants

Dots

Default background with subtle dot pattern. Use for most component previews.

<PreviewBlock background="dots">
  <Button>Example</Button>
</PreviewBlock>

Grid

Grid pattern for layout demonstrations.

<PreviewBlock background="grid">
  <Button>Example</Button>
</PreviewBlock>

None

No background. Use for components with their own backgrounds or full-width layouts.

<PreviewBlock background="none">
  <Button>Example</Button>
</PreviewBlock>

Pattern Customization

Customize the pattern size and color to match your design needs.

Custom Size

<PreviewBlock
  background="grid"
  patternSize={16}
>
  <Button>Tighter Grid</Button>
</PreviewBlock>

Custom Color

<PreviewBlock
  background="dots"
  patternColor="var(--blue-a3)"
>
  <Button>Blue Dots</Button>
</PreviewBlock>

Combined

<PreviewBlock
  background="grid"
  patternSize={32}
  patternColor="var(--gray-a6)"
>
  <Button>Larger, Darker Grid</Button>
</PreviewBlock>

Examples

Single Component

<PreviewBlock>
  <Button variant="solid" size="2">
    Click Me
  </Button>
</PreviewBlock>

Multiple Components

<PreviewBlock background="dots">
  <Flex gap="3">
    <Button variant="solid">Primary</Button>
    <Button variant="outline">Secondary</Button>
    <Button variant="ghost">Ghost</Button>
  </Flex>
</PreviewBlock>

With Custom Layout

<PreviewBlock background="grid">
  <Grid columns="3" gap="4">
    <Card>Card 1</Card>
    <Card>Card 2</Card>
    <Card>Card 3</Card>
  </Grid>
</PreviewBlock>

Full-Bleed Gradient

Use p="0" for gradients that should extend to the edges.

<PreviewBlock
  p="0"
  background={{
    backgroundColor: "hsla(259, 100%, 58%, 1)",
    backgroundImage: `url("data:image/svg+xml,..."), radial-gradient(circle at 100% 64%, hsla(45, 55%, 56%, 1) 1%, transparent 68%), radial-gradient(circle at 74% 91%, hsla(336, 54%, 73%, 1) 4%, transparent 77%)`,
    backgroundBlendMode: "overlay, normal, normal",
  }}
>
  <Text style={{ color: "white" }}>Full-bleed gradient</Text>
</PreviewBlock>

Image Background

Use p="0" with a background image for full-bleed photo backgrounds.

<PreviewBlock
  p="0"
  background={{
    backgroundColor: "hsl(220, 20%, 10%)",
    backgroundImage: "url(https://images.unsplash.com/photo-1764244666530-2b64b410a6c7?q=80&w=2670&auto=format&fit=crop)",
    backgroundSize: "cover",
    backgroundPosition: "center",
  }}
>
  <Text color="white">Image background</Text>
</PreviewBlock>

Custom Spacing

Adjust padding and margin to fit your layout needs.

<PreviewBlock px="6" py="8" my="6">
  <Button>More Spacious</Button>
</PreviewBlock>

Design Decisions

• Centered layout: Components are centered both horizontally and vertically
• Min height: 240px minimum height ensures adequate preview space
• Soft card: Uses soft Card variant for subtle container
• Font family override: Sets fontFamily="sans" via Theme to ensure consistent preview rendering
• Spacing: Default vertical margin (my="3") for separation from surrounding content

Accessibility

Preview Block provides accessible component previews:

Structure

• Wraps content in semantic Box and Card components
• Maintains proper document outline
• No special ARIA attributes needed (presentational container)

Visual

• Background patterns use CSS variables that respect color mode
• Sufficient contrast between background and components
• Patterns are subtle and don't interfere with component visibility

Changelog

Added

• Preview Block component for live component demos
• Dots background pattern (default)
• Grid background pattern
• None background option
• Centered layout with flexible spacing
• patternSize prop for customizing pattern spacing
• patternColor prop for customizing pattern color
• width and height props for sizing
• variant prop for card styling
• appearance prop for theme control
• showThemeToggle prop for interactive theme switching
• Padding props (p, px, py, pt, pr, pb, pl) for inner content spacing
• Margin props (m, mx, my, mt, mr, mb, ml) for outer container spacing