grommet
components

Box

a container that lays out its contents in one direction

Storybook
CodeSandbox

Props

a11yTitle

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

"a user friendly label for screen readers"

align

How to align the contents along the cross axis.
"start"
"center"
"end"
"baseline"
"stretch"

alignContent

How to align the contents when there is extra space in the cross axis.

"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.

"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.

"fadeIn"
"fadeOut"
"jiggle"
"pulse"
"slideUp"
"slideDown"
"slideLeft"
"slideRight"
"zoomIn"
"zoomOut"
{
  "type": "...",
  "delay": 0,
  "duration": 1000,
  "size": "xsmall"
}
["fadeIn", "slideDown", "..."]

as

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

background

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.

"neutral-1"
"url(//my.com/assets/img.png)"
{
  "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.
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"full"
"1/2"
"1/3"
"2/3"
"1/4"
"2/4"
"3/4"
"auto"

border

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

true
false
"top"
"left"
"bottom"
"right"
"between"
"horizontal"
"vertical"
"all"
{
  "color": "border",
  "size": "medium",
  "style": "dashed",
  "side": "all"
}
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.
"row""column""row-responsive""row-reverse""column-reverse"

elevation

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

"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.
"horizontal""vertical"truefalse

flex

Whether flex-grow and/or flex-shrink is true and at a desired factor.
"grow""shrink"truefalse
{
grow:
"number,"
shrink: number
}

focusIndicator

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

truefalse

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 choldren of the Fragment.

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

gridArea

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

"a parent grid area name"

height

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

hoverIndicator

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

truefalse"string""background"
{
color:
"string,"
dark:
"boolean""string,"
image:
"string,"
light:
"string,"
position:
"string,"
opacity:
"string""boolean""number""weak""medium""strong,"
repeat:
"no-repeat""repeat""string,"
size:
"cover""contain""string"
}

justify

How to align the contents along the main axis.
"around""between""center""end""evenly""start""stretch"

margin

The amount of margin around the component. An object can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.

"xsmall"
"small"
"medium"
"large"
"xlarge"
{
  "vertical": "...",
  "horizontal": "...",
  "top": "...",
  "bottom": "...",
  "left": "...",
  "right": "..."
}

onClick

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

"function"

overflow

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

pad

The amount of padding around the box contents. An object can be specified to distinguish horizontal padding, vertical padding, and padding on a particular side of the box

"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"any CSS size"
{
  "vertical": "...",
  "horizontal": "...",
  "top": "...",
  "bottom": "...",
  "left": "...",
  "right": "..."
}

responsive

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

truefalse

round

How much to round the corners.
true
false
"xsmall"
"small"
"medium"
"large"
"xlarge"
"full"
"any CSS size"
{"size": "...", "corner": "top-left"}
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""function"

width

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

wrap

Whether children can wrap if they can't all fit.
truefalse"reverse"

Theme

global.animation

The animation configuration for the Box.
{
  "duration": "1s",
  "jiggle": {"duration": "0.1s"}
}

global.borderSize

The possible border sizes in the Box.
{
  "xsmall": "1px",
  "small": "2px",
  "medium": "4px",
  "large": "12px",
  "xlarge": "24px"
}

global.elevation

The possible shadows in Box elevation.
{
  "light": {
    "none": "none",
    "xsmall": "0px 1px 2px rgba(0, 0, 0, 0.20)",
    "small": "0px 2px 4px rgba(0, 0, 0, 0.20)",
    "medium": "0px 4px 8px rgba(0, 0, 0, 0.20)",
    "large": "0px 8px 16px rgba(0, 0, 0, 0.20)",
    "xlarge": "0px 12px 24px rgba(0, 0, 0, 0.20)"
  },
  "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 12px 24px rgba(255, 255, 255, 0.40)"
  }
}

global.colors.border

The color of the border
{
  "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
"active"

global.hover.background.opacity

The opacity of the default background when hovering
"medium"

global.hover.color

The color of the default background when hovering
{"dark": "white", "light": "black"}

global.opacity.medium

The value used when background opacity is set to true.
0.4

global.size

The possible sizes for width, height, and basis.
{
  "xxsmall": "48px",
  "xsmall": "96px",
  "small": "192px",
  "medium": "384px",
  "large": "768px",
  "xlarge": "1152px",
  "xxlarge": "1536px",
  "full": "100%"
}

box.extend

Any additional style for the Box.
"any CSS"
(props) => {}

box.responsiveBreakpoint

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

"small"

global.edgeSize

The possible sizes for any of gap, margin, and pad.
{
  "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.

{
  "small": {
    "value": 768,
    "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": 1536},
  "large": {}
}