grommet
docs
components

Box

a container that lays out its contents in one direction

Storybook
CodeSandbox
Github

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string
"a user friendly label for screen readers"

align

How to align the contents along the cross axis. Any 'align-items' valid CSS value is accepted, including composed ones such 'first baseline' and 'unsafe start'.

string
"start"
"center"
"end"
"baseline"
"stretch

alignContent

How to align the contents when there is extra space in the cross axis. Any 'align-content' valid CSS value is accepted, including composed ones such 'first baseline' and 'unsafe start'.

string
"start"
"center"
"end"
"between"
"around"
"stretch"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string
"start"
"center"
"end"
"stretch"

animation

Animation effect(s) to use. 'duration' and 'delay' should be in milliseconds. 'jiggle' and 'pulse' types are intended for small elements, like icons.

string
"fadeIn"
"fadeOut"
"jiggle"
"pulse"
"rotateLeft"
"rotateRight"
"slideUp"
"slideDown"
"slideLeft"
"slideRight"
"zoomIn"
"zoomOut"
object

{
  type: "...",
  delay: 0,
  duration: 1000,
  size: "xsmall"
}
array
["fadeIn", "slideDown", "..."]

as

The DOM tag or react component to use for the element.

string

The name of a component.

"div"
function
() => {}
element
<span />

background

The background of the box. Either a color identifier to use for the background color. For example: 'neutral-1'. Or, a 'url()' for an image. Dark is not needed if color is provided.

string

A color or image url.

"neutral-1"
"url(//my.com/assets/img.png)"
object

{
  color: "neutral-1",
  dark: true,
  opacity: true,
  position: "bottom",
  repeat: "no-repeat",
  size: "cover",
  image: "url(//my.com/assets/img.png)"
}
              
{ dark: "light-2", light: "dark-2" }
where opacity could be:
"weak"
"medium"
"strong"
true
where position could be:
any CSS for background-position
where repeat could be:
"no-repeat"
"repeat"
"string"
where size could be:
"cover"
"contain"
"string"

basis

A fixed or relative size along its container's main axis.

string
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"xxlarge"
"full"
"1/2"
"1/3"
"2/3"
"1/4"
"2/4"
"3/4"
"auto"

border

A border around the Box.

boolean
true
false
string

The 'between' option will place a border in the gap between child elements. You must have a 'gap' to use 'between'.

"top"
"left"
"bottom"
"right"
"start"
"end"
"horizontal"
"vertical"
"all"
"between"
object

{
  color: string | { dark: string, light: string },
  size: "medium",
  style: "dashed",
  side: "all"
}
array

An array of objects defining the border for different sides of the Box.


[
  {
    color: "black",
    size: "small",
    style: "solid",
    side: "top"
  },
  {
    color: "black",
    size: "medium",
    style: "dotted",
    side: "bottom"
  }
]
where size could be:
"xsmall"
"small"
"medium"
"large"
"xlarge"
"any CSS size"
where style could be:
"solid"
"dashed"
"dotted"
"double"
"groove"
"ridge"
"inset"
"outset"
"hidden"
where side could be:
"top"
"left"
"bottom"
"right"
"horizontal"
"vertical"
"all"

direction

The orientation to layout the child components in.

string
"row"
"column"
"row-responsive"
"row-reverse"
"column-reverse"

elevation

Elevated height above the underlying context, indicated via a drop shadow.

string
"none"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"any custom elevation name in the current theme"

fill

Whether the width and/or height should fill the container.

string
"horizontal"
"vertical"
boolean
true
false

flex

Whether flex-grow and/or flex-shrink is true and at a desired factor.

string
"grow"
"shrink"
boolean
true
false
object
{ grow: number, shrink: number }

focusIndicator

When interactive via 'onClick', whether it should receive a focus outline.

boolean
true
false

gap

The amount of spacing between child elements. This should not be used in conjunction with 'wrap' as the gap elements will not wrap gracefully. If a child is a Fragment, Box will not add a gap between the children of the Fragment.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"none"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"any CSS size"

gridArea

The name of the area to place this inside a parent Grid.

string
"a parent grid area name"

height

A fixed height.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"xxlarge"
"any CSS size"
object
{ min: "...", max: "..." }

hoverIndicator

When 'onClick' has been specified, the hover indicator to apply when the user is mousing over the box.

boolean
true
false
string
"background"
object

An object defining the background or the background and elevation.


{
  color: "...",
  dark: "...",
  image: "string",
  position: "string",
  opacity: "...",
  repeat: "...",
  size: "...",
  light: "string"
}
              

{
  background: {
    color: "...",
    dark: "...",
    image: "string",
    position: "string",
    opacity: "...",
    repeat: "...",
    size: "...",
    light: "string"
  },
  elevation: "..."
}
where color could be:
"string"
{ dark: "string", light: "string" }
where dark could be:
boolean
"string"
where opacity could be:
boolean
number
"weak"
"medium"
"strong"
where repeat could be:
"no-repeat"
"repeat"
"string"
where size could be:
"cover"
"contain"
"string"
where elevation could be:
"none"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"string"

justify

How to align the contents along the main axis.

string
"around"
"between"
"center"
"end"
"evenly"
"start"
"stretch"

margin

The amount of margin around the component.

string
"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

onClick

Click handler. Setting this property adds additional attributes to the DOM for accessibility.

function
() => {}

overflow

How to handle Box overflow.

string
"auto"
"hidden"
"scroll"
"visible"
"any CSS overflow"
object
{ vertical: "...", horizontal: "..." }

pad

The amount of padding around the Box contents.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"any CSS size"
object

An object can be specified to distinguish horizontal padding, vertical padding, and padding on a particular side.


{
  vertical: "...",
  horizontal: "...",
  top: "...",
  bottom: "...",
  left: "...",
  right: "...",
  start: "...",
  end: "..."
}

responsive

Whether margin, pad, and border sizes should be scaled for mobile environments.

boolean
true
false

round

How much to round the corners.

boolean
true
false
string
"xsmall"
"small"
"medium"
"large"
"xlarge"
"full"
"any CSS size"
object
{ size: "...", corner: "..." }
where corner could be:
"top"
"left"
"bottom"
"right"
"top-left"
"top-right"
"bottom-left"
"bottom-right"

tag

The DOM tag to use for the element. NOTE: This is deprecated in favor of indicating the DOM tag via the 'as' property.

string

The name of a component.

"div"
function
() => {}

width

A fixed width.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"xxlarge"
"any CSS size"
object
{ min: "...", max: "..." }

wrap

Whether children can wrap if they can't all fit.

boolean
true
false
string
"reverse"

React/DOM Properties

At its core, the Box component is a regular <div> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for div elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

global.animation

The animation configuration for the Box.

object

{
  duration: '1s',
  jiggle: { duration: '0.1s' }
}

global.borderSize

The possible border sizes in the Box.

object

{
  xsmall: '1px',
  small: '2px',
  medium: '4px',
  large: '12px',
  xlarge: '24px,
}

global.elevation

The possible shadows in Box elevation.

object

{
  light: {
    none: 'none',
    xsmall: '0px 1px 2px rgba(100, 100, 100, 0.50)',
    small: '0px 2px 4px rgba(100, 100, 100, 0.50)',
    medium: '0px 3px 8px rgba(100, 100, 100, 0.50)',
    large: '0px 6px 12px rgba(100, 100, 100, 0.50)',
    xlarge: '0px 8px 16px rgba(100, 100, 100, 0.50)',
  },
  dark: {
    none: 'none',
    xsmall: '0px 2px 2px rgba(255, 255, 255, 0.40)',
    small: '0px 4px 4px rgba(255, 255, 255, 0.40)',
    medium: '0px 6px 8px rgba(255, 255, 255, 0.40)',
    large: '0px 8px 16px rgba(255, 255, 255, 0.40)',
    xlarge: '0px 10px 24px rgba(255, 255, 255, 0.40)',
  },
}

global.colors.border

The color of the border.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.


{ 
  dark: rgba(255, 255, 255, 0.33), 
  light: rgba(0, 0, 0, 0.33), 
}

global.hover.background.color

The color of the default background when hovering.

string

A hex, name, or rgb value.

"active"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

global.hover.background.opacity

The opacity of the default background when hovering.

string
"medium"
number
0.5

global.hover.color

The color of the default background when hovering.

string

A hex, name, or rgb value.

"black"
object

An object with a color for dark and light modes.

{ dark: "white", light: "black" }

global.opacity.medium

The value used when background opacity is set to true.

number
0.4

global.size

The possible sizes for width, height, and basis.

object

{
  xxsmall: '48px',
  xsmall: '96px',
  small: '192px',
  medium: '384px',
  large: '768px',
  xlarge: '1152px',
  xxlarge: '1536px',
  full: '100%',
}

box.extend

Any additional style for the Box.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

box.responsiveBreakpoint

The actual breakpoint to trigger changes in the border, direction, gap, margin, pad, and round.

string
"small"

global.edgeSize

The possible sizes for any of gap, margin, and pad.

object

{
  edgeSize: {
    none: '0px',
    hair: '1px',
    xxsmall: '3px',
    xsmall: '6px',
    small: '12px',
    medium: '24px',
    large: '48px',
    xlarge: '96px',
    responsiveBreakpoint: 'small',
  },
}

global.breakpoints

The possible breakpoints that could affect border, direction, gap, margin, pad, and round.

object

{
  small: {
    value: '768px',
    borderSize: {
      xsmall: '1px',
      small: '2px',
      medium: '4px',
      large: '6px',
      xlarge: '12px',
    },
    edgeSize: {
      none: '0px',
      hair: '1px',
      xxsmall: '2px',
      xsmall: '3px',
      small: '6px',
      medium: '12px',
      large: '24px',
      xlarge: '48px',
    },
    size: {
      xxsmall: '24px',
      xsmall: '48px',
      small: '96px',
      medium: '192px',
      large: '384px',
      xlarge: '768px',
      full: '100%',
    },
  },
  medium: { value: '1536px' },
  large: {},
}