@primer/react-brand

--- title: Box description: Use a box to simplify the process of applying one-off styles to an element keywords: ['layout'] ready: true source: https://github.com/primer/brand/blob/main/packages/react/src/Box/Box.tsx storybook: '/brand/storybook/?path=/story/components-box--default' --- ```js import {Box} from '@primer/react-brand' ``` ## Examples Box requires the `dir` attribute to be set on the `<html />` element to ensure that directional padding and margin values are applied correctly. ### Default The `Box` component, by default, represents an empty `<div>` element with no predefined styles applied to it. ```jsx <Box>With GitHub Copilot, you’re always in charge.</Box> ``` ### Uniform padding Use `padding` to apply equal inner spacing to all sides of an element. ```jsx <> <Stack direction="horizontal" alignItems="center" flexWrap="wrap"> <Box padding="condensed" className="bg-red-lines"> condensed </Box> <Box padding="normal" className="bg-red-lines"> normal </Box> <Box padding="spacious" className="bg-red-lines"> spacious </Box> </Stack> <Stack direction="horizontal" alignItems="center" flexWrap="wrap"> <Box padding={24} className="bg-red-lines"> 24 </Box> <Box padding={32} className="bg-red-lines"> 32 </Box> <Box padding={48} className="bg-red-lines"> 48 </Box> <Box padding={64} className="bg-red-lines"> 64 </Box> <Box padding={96} className="bg-red-lines"> 96 </Box> </Stack> </> ``` ### Directional padding Apply internal spacing to a specific side. Directional padding is implemented with CSS logical properties and accepts functional spacing names, or values from the base scale. ```jsx <Stack direction="horizontal" alignItems="center" flexWrap="wrap"> <Box paddingBlockStart={64} className="bg-red-lines"> block start </Box> <Box paddingInlineEnd={64} className="bg-red-lines"> inline end </Box> <Box paddingBlockEnd={64} className="bg-red-lines"> block end </Box> <Box paddingInlineStart={64} className="bg-red-lines"> inline start </Box> </Stack> ``` ### Uniform margin Use `margin` to apply equal outer spacing to all sides of an element. ```jsx <> <Stack direction="horizontal" alignItems="center" flexWrap="wrap"> <Box className="bg-yellow-lines"> <Box margin="condensed" className="bg-red-lines"> condensed </Box> </Box> <Box className="bg-yellow-lines"> <Box margin="normal" className="bg-red-lines"> normal </Box> </Box> <Box className="bg-yellow-lines"> <Box margin="spacious" className="bg-red-lines"> spacious </Box> </Box> </Stack> <Stack direction="horizontal" alignItems="center" flexWrap="wrap"> <Box className="bg-yellow-lines"> <Box margin={24} className="bg-red-lines"> 24 </Box> </Box> <Box className="bg-yellow-lines"> <Box margin={32} className="bg-red-lines"> 32 </Box> </Box> <Box className="bg-yellow-lines"> <Box margin={48} className="bg-red-lines"> 48 </Box> </Box> <Box className="bg-yellow-lines"> <Box margin={64} className="bg-red-lines"> 64 </Box> </Box> <Box className="bg-yellow-lines"> <Box margin={96} className="bg-red-lines"> 96 </Box> </Box> </Stack> </> ``` ### Directional margin Apply external spacing to a specific side. Directional margins are implemented with CSS logical properties and accepts functional spacing names, or values from the base scale. ```jsx <Stack direction="horizontal" alignItems="center" flexWrap="wrap"> <Box className="bg-yellow-lines"> <Box marginBlockStart={64} className="bg-red-lines"> block start </Box> </Box> <Box className="bg-yellow-lines"> <Box marginInlineEnd={64} className="bg-red-lines"> inline end </Box> </Box> <Box className="bg-yellow-lines"> <Box marginBlockEnd={64} className="bg-red-lines"> block end </Box> </Box> <Box className="bg-yellow-lines"> <Box marginInlineStart={64} className="bg-red-lines"> inline start </Box> </Box> </Stack> ``` ### Responsive spacing All padding and margin options can be configured for indivisual viewports: Each viewport entry is applied using a `min-width` media query. ```jsx <Stack direction="horizontal" alignItems="center" flexWrap="wrap"> <Box className="bg-yellow-lines"> <Box margin={{ narrow: 48, regular: 96, wide: 128, }} className="bg-red-lines" > margin </Box> </Box> <Box padding={{ narrow: 48, regular: 96, wide: 128, }} className="bg-red-lines" > padding </Box> </Stack> ``` ### Border radius ```jsx <Stack direction="horizontal" flexWrap="wrap"> <Box borderRadius="small" padding="spacious" className="bg-red-lines"> small </Box> <Box borderRadius="medium" padding="spacious" className="bg-red-lines"> medium </Box> <Box borderRadius="large" padding="spacious" className="bg-red-lines"> large </Box> <Box borderRadius="full" padding="spacious" className="bg-red-lines"> full </Box> </Stack> ``` ### Borders ```jsx <Stack direction="horizontal" flexWrap="wrap"> <Box backgroundColor="subtle" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious"> thin </Box> <Box backgroundColor="subtle" borderWidth="thick" borderColor="default" borderStyle="solid" padding="spacious"> thick </Box> <Box backgroundColor="subtle" borderWidth="thicker" borderColor="default" borderStyle="solid" padding="spacious"> thicker </Box> </Stack> ``` ### Background colors ```jsx <Stack direction="horizontal" flexWrap="wrap"> <Box backgroundColor="default" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious"> default </Box> <Box backgroundColor="subtle" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious"> subtle </Box> <Box backgroundColor="inset" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious"> inset </Box> <Box backgroundColor="overlay" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious"> overlay </Box> <Box backgroundColor="var(--base-color-scale-green-5)" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious" > Custom </Box> </Stack> ``` ## Component props ### Box | Name | Type | Default | Description | | :----------------------- | :----------------------- | :---------: | :-------------------------------------------------------------------------- | | `padding` | `BoxSpacingValues` | `undefined` | Adds padding to all internal sides of the Box. | | `paddingBlockStart` | `BoxSpacingValues` | `undefined` | Adds padding to the internal block start (top) side of the Box. | | `paddingRight` | `BoxSpacingValues` | `undefined` | Adds padding to the internal inline end (right) of the Box. | | `paddingBlockEnd` | `BoxSpacingValues` | `undefined` | Adds padding to the internal block end (bottom) side of the Box. | | `paddingLeft` | `BoxSpacingValues` | `undefined` | Adds padding to the internal inline start (left) side of the Box. | | `margin` | `BoxSpacingValues` | `undefined` | Adds margin to all external sides of the Box. | | `marginBlockStart` | `BoxSpacingValues` | `undefined` | Adds margin to the external block start (top) side of the Box. | | `marginInlineEnd` | `BoxSpacingValues` | `undefined` | Adds margin to the external inline end (right) side of the Box. | | `marginBlockEnd` | `BoxSpacingValues` | `undefined` | Adds margin to the external block end (bottom) side of the Box. | | `marginInlineStart` | `BoxSpacingValues` | `undefined` | Adds margin to the external inline start (left) side of the Box. | | `backgroundColor` | | `undefined` | Applies a system-level background color to the Box. | | `borderRadius` | `BoxBorderRadiusOptions` | `undefined` | Applies a system-level border radius value to the Box. | | `borderWidth` | `BoxBorderWidthOptions` | `undefined` | Applies a system-level border width value to the Box. | | `borderBlockStartWidth` | `BoxBorderWidthOptions` | `undefined` | Applies a system-level border width value to block-start side of the Box. | | `borderInlineEndWidth` | `BoxBorderWidthOptions` | `undefined` | Applies a system-level border width value to inline-end side of the Box. | | `borderBlockEndWidth` | `BoxBorderWidthOptions` | `undefined` | Applies a system-level border width value to block-end side of the Box. | | `borderInlineStartWidth` | `BoxBorderWidthOptions` | `undefined` | Applies a system-level border width value to inline-start side of the Box. | | `borderColor` | `BoxBorderColorOptions` | `undefined` | Applies a system-level border color value to the Box. | | `borderStyle` | | `undefined` | Applies border style. Values correspond to the CSS `border-style` property. |