Box | Mineral UI

Box component provides an easy way to apply standardized size & space to your layout.

Box is the basis of the other layout components: Flex, FlexItem, Grid, GridItem, and StartEnd.

Examples #

Import Syntax #

import Box from 'mineral-ui/Box';

Note

Layout components, like Box, have no default visual style or margin/padding. They are rendered with background colors, borders, margins, and padding in the examples below for illustrative purposes.

Basic Usage #

Use Box to easily apply margin, padding, and/or width.

<DemoLayout>
  <Box>A</Box>
  <Box padding="lg">B</Box>
  <Box marginRight="50%">C</Box>
  <Box marginHorizontal="auto" width="10em">D</Box>
</DemoLayout>

Spacing #

Values for margin & padding can be a spacing theme variable or a custom string or number.

In order of precedence, Box accepts the following spacing props:

margin[Bottom|Left|Right|Top]
marginStart (left, for left-to-right languages; right, for RTL languages)
marginEnd (right, for left-to-right languages; left, for RTL languages)
marginHorizontal (left & right)
marginVertical (top & bottom)
margin (all sides)

Numbers < 1, e.g. 1/2, will be converted to a percentage. Numbers ≥ 1 will be appended with px. String values, e.g. "4em" or "20%", will be passed directly.

The same applies for padding.

none

6em

120

1/3

/*
 * Spacing theme variables:
 * 'xxs', 'xs', 'sm', 'md', 'lg', 'xl', 'xxl'
 */
<DemoLayout>
  <Box>none</Box>
  <Box marginRight="xl">xl</Box>
  <Box marginRight="6em">6em</Box>
  <Box marginRight={120}>120</Box>
  <Box marginRight={1/3}>1/3</Box>
</DemoLayout>

Width #

By default, (unless the inline prop is set to true), Box will fill the available width. Set the width prop to define a width instead.

Numbers < 1, e.g. 1/2, will be converted to a percentage. Numbers ≥ 1 will be appended with px. String values, e.g. "4em" or "20%", will be passed directly.

<DemoLayout>
  <Box width="10em">A</Box>
  <Box width={100}>B</Box>
  <Box width={1/3}>C</Box>
</DemoLayout>

Height #

By default, Box will stretch in height to fit its contents. Set the height prop to define a height instead.

Numbers < 1, e.g. 1/2, will be converted to a percentage. Numbers ≥ 1 will be appended with px. String values, e.g. "4em" or "20%", will be passed directly.

<DemoLayout>
  <Box height="10em">A</Box>
  <Box height={100}>B</Box>
  <Box height={1/3}>C</Box>
</DemoLayout>

Inline #

By default, Box renders as a block-level element. Use inline to render as inline-block.

<DemoLayout>
  <Box inline>A</Box>
  <Box inline width={100}>B</Box>
  <Box inline>C</Box>
</DemoLayout>

Element #

Change the rendered element for Box with the as prop.

This renders as a section, instead of a div.

<Box as="section">This renders as a section, instead of a div.</Box>

Responsive #

Many of the properties for Box can be responsive:

Provide an array of breakpoints, which will be used in the (min-width) media queries used for responsive properties.
Those breakpoint values can either be a number (converted to px) or a key from the theme (e.g. the default mineralTheme has 'narrow', 'medium', and 'wide').
For each responsive property, instead of passing a single value, pass an array of values that is one longer than the breakpoints array. The first value applies when no breakpoint matches, the second value applies when the first breakpoint matches, and so on.
If you don't need to change a value at a breakpoint, you can pass null to skip that breakpoint for that property.

The code in the example below exhibits the following behavior:

When the viewport is less than 800px wide, it will have a right margin of 50px.
When the viewport is between 800px and 1024px (the 'wide' breakpoint theme variable), it will have a right margin of 100px.
When the viewport is at least 1024px wide, it will have a right margin of 150px.

<Box
  breakpoints={[800, 'wide']}
  marginRight={[50, 100, 150]}>
  A
</Box>

Bidirectionality #

Box reverses some of its properties when the direction theme variable is set to rtl (right-to-left).

اليسار

بداية

النهاية

<div dir="rtl">
  <ThemeProvider theme={{ direction: 'rtl' }}>
    <DemoLayout>
      <Box marginLeft="lg">اليسار</Box>
      <Box marginStart="lg">بداية</Box>
      <Box marginEnd="lg">النهاية</Box>
    </DemoLayout>
  </ThemeProvider>
</div>

API & Theme #

Box Props #

The Box component takes the following React props.

Name	Type	Description
breakpoints	Array<number \| string>	Media query (min-width) breakpoints along which to apply props marked "[Responsive-capable]
height		Sets the box height. [Responsive-capable]
inline	boolean \| Array<boolean \| null>	Renders Box as an inline-block [Responsive-capable]
margin		Applies a margin on all sides [Responsive-capable]
marginBottom		Applies a bottom margin [Responsive-capable]
marginEnd		Applies a right margin when the language is left-to-right and left margin for RTL languages [Responsive-capable]
marginHorizontal		Applies left & right margins [Responsive-capable]
marginLeft		Applies a left margin [Responsive-capable]
marginRight		Applies a right margin [Responsive-capable]
marginStart		Applies a left margin when the language is left-to-right and right margin for RTL languages [Responsive-capable]
marginTop		Applies a top margin [Responsive-capable]
marginVertical		Applies top & bottom margins [Responsive-capable]
padddingEnd		Applies right padding when the language is left-to-right and left padding for RTL languages [Responsive-capable]
padddingStart		Applies left padding when the language is left-to-right and right padding for RTL languages [Responsive-capable]
padding		Applies padding to all sides [Responsive-capable]
paddingBottom		Applies bottom padding [Responsive-capable]
paddingHorizontal		Applies left & right padding [Responsive-capable]
paddingLeft		Applies left padding [Responsive-capable]
paddingRight		Applies right padding [Responsive-capable]
paddingTop		Applies bottom padding [Responsive-capable]
paddingVertical		Applies top & bottom margins [Responsive-capable]
width		Sets the box width [Responsive-capable]

Note

All of the margin/padding props above are applied in a specific order of precedence.

Undocumented properties, including as and css, will be applied to the root element.

Usage #

When/How to Use #

Box serves as an invisible building block for the layout and structure of your app. Use it to provide consistent size and spacing around components.

In general, do not display content directly within Box. Rather, wrap Box around other components.

Best Practices #

Wrap Box around other components to apply spacing from the theme.

Use Box's marginStart & marginEnd props to apply directionally-appropriate left/right margins.

Don't use Box to display content directly. Wrap Box around components instead.

This is some text, without the proper text styles, because it is directly inside a Box.