CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-theme-ui

The Design Graph Framework - a library for creating themeable user interfaces based on constraint-based design principles

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

components.mddocs/

Theme UI Components

A comprehensive component library built on top of the Theme UI design system. All components are built with TypeScript and support theme-aware styling through the sx prop and system props.

Core System Props

All Theme UI components inherit from the base Box component and support system props for consistent styling:

interface BoxSystemProps {
  // Spacing props
  margin?: ResponsiveStyleValue<string | number>
  marginTop?: ResponsiveStyleValue<string | number>
  marginRight?: ResponsiveStyleValue<string | number>
  marginBottom?: ResponsiveStyleValue<string | number>
  marginLeft?: ResponsiveStyleValue<string | number>
  marginX?: ResponsiveStyleValue<string | number>
  marginY?: ResponsiveStyleValue<string | number>
  m?: ResponsiveStyleValue<string | number>
  mt?: ResponsiveStyleValue<string | number>
  mr?: ResponsiveStyleValue<string | number>
  mb?: ResponsiveStyleValue<string | number>
  ml?: ResponsiveStyleValue<string | number>
  mx?: ResponsiveStyleValue<string | number>
  my?: ResponsiveStyleValue<string | number>
  
  padding?: ResponsiveStyleValue<string | number>
  paddingTop?: ResponsiveStyleValue<string | number>
  paddingRight?: ResponsiveStyleValue<string | number>
  paddingBottom?: ResponsiveStyleValue<string | number>
  paddingLeft?: ResponsiveStyleValue<string | number>
  paddingX?: ResponsiveStyleValue<string | number>
  paddingY?: ResponsiveStyleValue<string | number>
  p?: ResponsiveStyleValue<string | number>
  pt?: ResponsiveStyleValue<string | number>
  pr?: ResponsiveStyleValue<string | number>
  pb?: ResponsiveStyleValue<string | number>
  pl?: ResponsiveStyleValue<string | number>
  px?: ResponsiveStyleValue<string | number>
  py?: ResponsiveStyleValue<string | number>
  
  // Color props
  color?: ResponsiveStyleValue<string>
  backgroundColor?: ResponsiveStyleValue<string>
  bg?: ResponsiveStyleValue<string>
  opacity?: ResponsiveStyleValue<string | number>
}

interface BoxOwnProps extends BoxSystemProps {
  as?: React.ElementType
  variant?: string
  css?: Interpolation<any>
  sx?: ThemeUIStyleObject<Theme>
}

Layout Components

Box

The foundational component that all other components are built upon. Provides system props for spacing, colors, and theme-aware styling.

interface BoxProps extends Omit<
  Assign<React.ComponentPropsWithRef<'div'>, BoxOwnProps>,
  'ref'
> {}

const Box: ForwardRef<any, BoxProps>

Usage:

<Box p={3} bg="primary" color="white">
  Content with padding and background
</Box>

<Box as="section" mx="auto" maxWidth="container">
  Semantic HTML with system props
</Box>

Flex

A flexbox container component with display: flex applied by default.

interface FlexProps extends BoxProps {}

const Flex: ForwardRef<HTMLElement, FlexProps>

Usage:

<Flex alignItems="center" justifyContent="space-between">
  <Text>Left content</Text>
  <Button>Right action</Button>
</Flex>

<Flex direction="column" gap={3}>
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</Flex>

Grid

CSS Grid layout component with configurable columns and responsive design.

interface GridProps extends BoxProps {
  /**
   * Minimum width of child elements
   */
  width?: ResponsiveStyleValue<string | number>
  /**
   * Number of columns to use for the layout (cannot be used in conjunction with the width prop)
   */
  columns?: ResponsiveStyleValue<string | number>
  /**
   * Space between child elements
   */
  gap?: ResponsiveStyleValue<string | number>
  /**
   * Auto-repeat track behaviour (default is fit)
   */
  repeat?: 'fit' | 'fill'
}

const Grid: ForwardRef<HTMLDivElement, GridProps>

Usage:

<Grid columns={[1, 2, 3]} gap={3}>
  <Card>Card 1</Card>
  <Card>Card 2</Card>
  <Card>Card 3</Card>
</Grid>

<Grid width="250px" gap={4} repeat="fill">
  <Box>Auto-sized items</Box>
  <Box>Based on width</Box>
</Grid>

Container

Centered, max-width layout component for page content.

interface ContainerProps extends BoxProps {}

const Container: ForwardRef<HTMLDivElement, ContainerProps>

Usage:

<Container>
  <Heading>Page Title</Heading>
  <Text>Page content with max-width constraint</Text>
</Container>

<Container variant="narrow" py={4}>
  <form>Form content</form>
</Container>

AspectRatio

Component for maintaining fluid-width aspect ratios, useful for responsive media.

interface AspectRatioProps extends BoxProps {
  ratio?: number
}

const AspectRatio: ForwardRef<HTMLDivElement, AspectRatioProps>

Usage:

<AspectRatio ratio={16/9}>
  <iframe src="video-url" />
</AspectRatio>

<AspectRatio ratio={1}>
  <Image src="square-image.jpg" />
</AspectRatio>

Typography Components

Text

Primitive typographic component for inline and block text.

interface TextProps extends BoxProps {}

const Text: ForwardRef<HTMLDivElement, TextProps>

Usage:

<Text fontSize={2} color="muted">
  Body text with theme styles
</Text>

<Text as="span" variant="caption">
  Inline text with variant
</Text>

Heading

Semantic heading component that defaults to h2 element.

interface HeadingProps extends Assign<
  React.ComponentPropsWithRef<'h2'>, 
  BoxOwnProps
> {}

const Heading: ForwardRef<HTMLHeadingElement, HeadingProps>

Usage:

<Heading as="h1" variant="display">
  Main Page Title
</Heading>

<Heading fontSize={4} mb={3}>
  Section Heading
</Heading>

Paragraph

Text component specifically for paragraph content.

interface ParagraphProps extends Assign<
  React.ComponentPropsWithRef<'p'>, 
  BoxOwnProps
> {}

const Paragraph: ForwardRef<HTMLParagraphElement, ParagraphProps>

Form Components

Input

Form input component with theme-aware styling and autofill support.

interface InputProps extends Assign<
  React.ComponentPropsWithRef<'input'>, 
  BoxOwnProps
> {
  autofillBackgroundColor?: string
}

const Input: ForwardRef<HTMLInputElement, InputProps>

Usage:

<Input 
  placeholder="Enter text" 
  variant="primary"
  mb={3} 
/>

<Input 
  type="email" 
  autofillBackgroundColor="background"
  sx={{ borderRadius: 'lg' }}
/>

Textarea

Multi-line text input component.

interface TextareaProps extends Assign<
  React.ComponentPropsWithRef<'textarea'>, 
  BoxOwnProps
> {}

const Textarea: ForwardRef<HTMLTextAreaElement, TextareaProps>

Select

Dropdown select component with custom arrow styling.

interface SelectProps extends Assign<
  React.ComponentPropsWithRef<'select'>, 
  BoxOwnProps
> {
  arrow?: React.ReactElement
}

const Select: ForwardRef<HTMLSelectElement, SelectProps>

Usage:

<Select defaultValue="option1">
  <option value="option1">Option 1</option>
  <option value="option2">Option 2</option>
</Select>

<Select arrow={<CustomArrowIcon />}>
  <option>Custom arrow</option>
</Select>

Checkbox

Styled checkbox component with custom icons.

interface CheckboxProps extends Assign<
  React.ComponentPropsWithRef<'input'>, 
  BoxOwnProps
> {}

const Checkbox: ForwardRef<HTMLInputElement, CheckboxProps>

Usage:

<Label>
  <Checkbox defaultChecked />
  Accept terms and conditions
</Label>

<Checkbox variant="secondary" mr={2} />

Radio

Radio button component for single-choice selections.

interface RadioProps extends Assign<
  React.ComponentPropsWithRef<'input'>, 
  BoxOwnProps
> {}

const Radio: ForwardRef<HTMLInputElement, RadioProps>

Switch

Toggle switch component for boolean values.

interface SwitchProps extends Assign<
  React.ComponentPropsWithRef<'input'>, 
  BoxOwnProps
> {
  label?: string
}

const Switch: ForwardRef<HTMLInputElement, SwitchProps>

Usage:

<Switch label="Enable notifications" />

<Switch 
  label="Dark mode" 
  defaultChecked 
  variant="secondary"
/>

Slider

Range input component for numerical values.

interface SliderProps extends Assign<
  React.ComponentPropsWithRef<'input'>, 
  BoxOwnProps
> {}

const Slider: ForwardRef<HTMLInputElement, SliderProps>

Usage:

<Slider 
  min={0} 
  max={100} 
  defaultValue={50}
  mb={3}
/>

<Slider variant="accent" step={0.1} />

Label

Form label component for input descriptions.

interface LabelProps extends Assign<
  React.ComponentPropsWithRef<'label'>, 
  BoxOwnProps
> {}

const Label: ForwardRef<HTMLLabelElement, LabelProps>

Field

Wrapper component for form inputs with labels and styling.

interface FieldProps extends BoxProps {
  label: string
}

const Field: ForwardRef<HTMLDivElement, FieldProps>

Interactive Components

Button

Primary interactive component for user actions.

interface ButtonProps extends Assign<
  React.ComponentPropsWithRef<'button'>, 
  BoxOwnProps
> {}

const Button: ForwardRef<HTMLButtonElement, ButtonProps>

Usage:

<Button variant="primary" onClick={handleClick}>
  Primary Action
</Button>

<Button as="a" href="/link" variant="secondary">
  Link Button
</Button>

<Button size="large" disabled>
  Disabled Button
</Button>

IconButton

Button component optimized for icon content.

interface IconButtonProps extends Assign<
  React.ComponentPropsWithRef<'button'>, 
  BoxOwnProps
> {}

const IconButton: ForwardRef<HTMLButtonElement, IconButtonProps>

Usage:

<IconButton aria-label="Close">
  <CloseIcon />
</IconButton>

<IconButton variant="ghost" size="small">
  <EditIcon />
</IconButton>

MenuButton

Button component for menu triggers and dropdowns.

interface MenuButtonProps extends Assign<
  React.ComponentPropsWithRef<'button'>, 
  BoxOwnProps
> {}

const MenuButton: ForwardRef<HTMLButtonElement, MenuButtonProps>

Link

Styled link component that extends anchor elements.

interface LinkProps extends Assign<
  React.ComponentPropsWithRef<'a'>, 
  BoxOwnProps
> {}

const Link: ForwardRef<HTMLAnchorElement, LinkProps>

Usage:

<Link href="/about" variant="nav">
  About Page
</Link>

<Link as={RouterLink} to="/dashboard">
  Router Integration
</Link>

NavLink

Specialized link component for navigation menus.

interface NavLinkProps extends Assign<
  React.ComponentPropsWithRef<'a'>, 
  BoxOwnProps
> {}

const NavLink: ForwardRef<HTMLAnchorElement, NavLinkProps>

Close

Close button component with default close icon.

interface CloseProps extends Assign<
  React.ComponentPropsWithRef<'button'>, 
  BoxOwnProps
> {}

const Close: ForwardRef<HTMLButtonElement, CloseProps>

Display Components

Card

Container component for grouping related content.

interface CardProps extends BoxProps {}

const Card: ForwardRef<HTMLDivElement, CardProps>

Usage:

<Card p={4} bg="white" borderRadius="md">
  <Heading mb={2}>Card Title</Heading>
  <Text>Card content goes here</Text>
</Card>

<Card variant="elevated" maxWidth="sm">
  <Image src="hero.jpg" />
  <Box p={3}>
    <Heading>Article Title</Heading>
  </Box>
</Card>

Badge

Small labeling component for status and categorization.

interface BadgeProps extends BoxProps {}

const Badge: ForwardRef<HTMLDivElement, BadgeProps>

Usage:

<Badge variant="primary">New</Badge>
<Badge variant="success">Published</Badge>
<Badge variant="warning">Draft</Badge>

<Badge bg="accent" color="white" px={2}>
  Custom Badge
</Badge>

Avatar

User profile image component with consistent sizing.

interface AvatarProps extends ImageProps {
  size?: number | string
}

const Avatar: ForwardRef<HTMLImageElement, AvatarProps>

Usage:

<Avatar 
  src="/user-photo.jpg" 
  alt="User Name"
  size={48}
/>

<Avatar 
  src="/profile.jpg"
  size="large"
  variant="circular"
/>

Image

Responsive image component with theme variants.

interface ImageProps extends Assign<
  React.ComponentPropsWithRef<'img'>, 
  BoxOwnProps
> {}

const Image: ForwardRef<HTMLImageElement, ImageProps>

Usage:

<Image 
  src="/hero-image.jpg" 
  alt="Hero"
  width="100%"
  height="auto"
/>

<Image 
  src="/thumbnail.jpg"
  variant="rounded"
  maxWidth="200px"
/>

Divider

Visual separator component for content sections.

interface DividerProps extends BoxProps {}

const Divider: ForwardRef<HTMLHRElement, DividerProps>

Usage:

<Box>
  <Text>Section 1</Text>
  <Divider my={3} />
  <Text>Section 2</Text>
</Box>

<Divider variant="thick" color="primary" />

Feedback Components

Alert

Component for displaying important messages and notifications.

interface AlertProps extends BoxProps {}

const Alert: ForwardRef<HTMLDivElement, AlertProps>

Usage:

<Alert variant="info" mb={3}>
  <Text>Information message</Text>
</Alert>

<Alert variant="error">
  <Heading fontSize={1}>Error</Heading>
  <Text>Something went wrong</Text>
</Alert>

Message

Generic message component for user communication.

interface MessageProps extends BoxProps {}

const Message: ForwardRef<HTMLDivElement, MessageProps>

Progress

Horizontal progress bar for loading states.

interface ProgressProps extends Assign<
  React.ComponentPropsWithRef<'progress'>, 
  BoxOwnProps
> {}

const Progress: ForwardRef<HTMLProgressElement, ProgressProps>

Usage:

<Progress value={0.6} max={1} />

<Progress 
  value={75} 
  max={100}
  variant="accent"
  mb={3}
/>

Spinner

Loading indicator component.

interface SpinnerProps extends BoxProps {}

const Spinner: ForwardRef<HTMLDivElement, SpinnerProps>

Usage:

<Spinner />
<Spinner size={32} color="primary" />
<Spinner variant="dots" />

Data Visualization

Donut

Circular progress/chart component.

interface DonutProps extends BoxProps {
  value: number
  min?: number
  max?: number
  title?: string
  size?: number | string
  strokeWidth?: number | string
}

const Donut: ForwardRef<HTMLDivElement, DonutProps>

Usage:

<Donut 
  value={0.75} 
  size={100}
  title="75% Complete"
/>

<Donut 
  value={250} 
  min={0} 
  max={500}
  strokeWidth={4}
  color="success"
/>

Utility Components

SVG

Base SVG component for icons and graphics.

interface SVGProps extends Assign<
  SVGAttributes<SVGElement>, 
  BoxOwnProps
> {
  size?: number | string
}

const SVG: ForwardRef<SVGSVGElement, SVGProps>

Usage:

<SVG size={24} color="primary">
  <path d="..." />
</SVG>

<SVG viewBox="0 0 16 16" width={16} height={16}>
  <circle cx="8" cy="8" r="4" />
</SVG>

Embed

Component for embedding external content (videos, maps, etc.).

interface EmbedProps extends BoxProps {
  src: string
}

const Embed: ForwardRef<HTMLIFrameElement, EmbedProps>

AspectImage

Image component with built-in aspect ratio handling.

interface AspectImageProps extends ImageProps {
  ratio?: number
}

const AspectImage: ForwardRef<HTMLImageElement, AspectImageProps>

Theme Integration

All components integrate with the Theme UI theme object and support:

  • Variants: Pre-defined style combinations stored in theme
  • System Props: Responsive spacing, colors, and layout props
  • sx Prop: Runtime theme-aware styling with full CSS support
  • as Prop: Polymorphic component rendering
  • Responsive Design: Array syntax for breakpoint-specific values

Common Patterns

// Responsive design
<Box p={[2, 3, 4]} fontSize={[1, 2, 3]}>
  Responsive spacing and typography
</Box>

// Theme variants
<Button variant="secondary">Themed Button</Button>
<Card variant="elevated">Themed Card</Card>

// Runtime styling with sx
<Box sx={{
  background: 'gradient',
  '&:hover': { transform: 'scale(1.05)' },
  '@media (min-width: 768px)': { display: 'grid' }
}}>
  Advanced styling
</Box>

// Polymorphic components
<Button as="a" href="/link">Link Button</Button>
<Text as="label" htmlFor="input">Label Text</Text>

Theme Keys

Components look for variants in specific theme keys:

  • theme.buttons - Button variants
  • theme.text - Text and Heading variants
  • theme.forms - Form input variants
  • theme.cards - Card variants
  • theme.badges - Badge variants
  • theme.links - Link variants
  • theme.images - Image variants
  • theme.layout - Layout component variants
  • theme.grids - Grid variants

Each component can be customized by defining variants in the appropriate theme key, providing a scalable design system foundation.

docs

components.md

hooks-utilities.md

index.md

styling-system.md

theming.md

tile.json