Skip to content
Browse documentation
whisk/ui

Box

Wrap content with semantic HTML and shared utility props.

Overview

Box is a token-aware wrapper for grouping content, applying shared utility props, and choosing an appropriate HTML element.

Use when

You need a small token-aware wrapper, a semantic document region, or a themed surface around existing content.

Use instead

Use Stack, Flex, or Grid when the main job is arranging several children. Use Button or Link for an interactive action or destination.

Usage

Content inside a themed surface.

import { Box, Text } from "@smoothie-framework/whisk-react";

<Box as="section" padding={6} background="surface2" rounded="lg">
  <Text>Content inside a themed surface.</Text>
</Box>

Examples

Responsive surface

Use a responsive object when a layout value needs to change at a named breakpoint.

Full width at base, with a readable line length from md.

import { Box, Text } from "@smoothie-framework/whisk-react";

<Box
  padding={{ base: 3, md: 5 }}
  width={{ base: "full", md: "prose" }}
  background="surface1"
  rounded="md"
  border="sm"
  borderColor="borderSubtle"
>
  <Text>Full width at base, with a readable line length from md.</Text>
</Box>

Semantic host with as

Use as when the container carries meaning in the document structure.

Rendered as a section

Rendered as an article

import { Box, Stack, Text } from "@smoothie-framework/whisk-react";

<Stack gap={3}>
  <Box as="section" padding={3} background="surface2" rounded="md">
    <Text>Rendered as a section</Text>
  </Box>

  <Box as="article" padding={3} background="surface2" rounded="md">
    <Text>Rendered as an article</Text>
  </Box>

  <Box as="aside" padding={3} background="surface2" rounded="md">
    <Text>Rendered as complementary content</Text>
  </Box>
</Stack>

Composition

Use asChild when an existing element or router link should keep its own element type while receiving Box presentation props. It requires exactly one element child.

import { Box } from "@smoothie-framework/whisk-react";

<Box asChild padding={3} background="surface2" rounded="md">
  <a href="/settings">Open settings</a>
</Box>

Styled surface

Combine a border, radius, background, shadow, and nested content to make a contained panel.

Release panel

A composed surface built from themed primitives.

import { Box, Stack, Text } from "@smoothie-framework/whisk-react";

<Box padding={1} background="surface2" rounded="xl" border="sm" borderColor="borderSubtle" shadow="lg">
  <Box background="background" padding={4} rounded="lg">
    <Stack gap={1}>
      <Text weight="semibold">Release panel</Text>
      <Text color="subtle">A composed surface built from themed primitives.</Text>
    </Stack>
  </Box>
</Box>

Props

Component props

This component has no component-specific props.

Shared props

PropSupportedNotes
as / asChildYesChoose the rendered host with as, or merge the component props into one child with asChild.
Style propsYesUse the shared static style-prop surface. See Style props.
className / styleYesApplied to the rendered host.
refYesForwards to the rendered host.
Native HTML attributesYesNative attributes are forwarded to the rendered host.

Accessibility

Use as when the content has a meaningful semantic region. Box renders a div by default and does not add a role, keyboard behavior, or accessible name. Use Button or Link instead of adding an interactive role to Box.