Flex

Flex is a layout component with a very limited subset of the props available to Box and a special prop of its own.

Use this component for flexbox layouts, especially when even spacing between elements is desired (see the gap prop!).

also known as Row, Stack, Flexbox

Figma:

N/A

Responsive:

Ready

Adaptive:

N/A

Props

Component props
Name	Type	Default
`alignContent`	`"start" \| "end" \| "center" \| "between" \| "around" \| "evenly" \| "stretch"`	-
	Aligns the flex container's lines within when there is extra space in the cross axis, similar to how `justify-content` aligns individual items within the main axis.
`alignItems`	`"start" \| "end" \| "center" \| "baseline" \| "stretch"`	-
	Defines the default behaviour for how flex items are laid out along the cross axis on the current line. Think of it as the `justify-content` version for the cross axis (perpendicular to the main axis). Also available in responsive sizes: `smAlignItems`, `mdAlignItems`, `lgAlignItems`. See the Screen size page to learn more about viewport breakpoints in web.
`alignSelf`	`"auto" \| "start" \| "end" \| "center" \| "baseline" \| "stretch"`	-
	Allows the default alignment (or the one specified by `align-items`) to be overridden for individual flex items.
`children`	`React.Node`	-
	Note that each child will be automatically wrapped in Flex.Item to apply various styles. If specific flex styles are needed on a child, you can manually wrap it in Flex.Item to apply those styles. See the Applying flex properties to children example to learn more.
`dataTestId`	`string`	-
	Used to identify the element for testing purposes.
`direction`	`"row" \| "column"`	`"row"`
	Establishes the main axis, thus defining the direction flex items are placed in the flex container.
`flex`	`"grow" \| "shrink" \| "none"`	`"shrink"`
	Defines how a flex item will be sized. "grow", equivalent to "flex: 1 1 auto", will size Flex relative to its parent, growing and shrinking based on available space. "shrink", equivalent to "flex: 0 1 auto" (the browser default), allows Flex to shrink if compressed but not grow if given extra space. Finally, "none", equivalent to "flex: 0 0 auto", preserves Flex's size based on child content regardless of its container's size.
`gap`	`Gap \| { row: Gap; column: Gap; }`	`0`
	Defines spacing between each child along the main and cross axes. Use an object to define different spacing for rows and columns. See the Gap variant to learn more.
`height`	`number \| string`	-
	Use numbers for pixels: `height={100}` and strings for percentages: `height="100%"`.
`justifyContent`	`"start" \| "end" \| "center" \| "between" \| "around" \| "evenly"`	-
	Defines the alignment along the main axis. It helps distribute extra free space left over when either all the flex items on a line are inflexible, or are flexible but have reached their maximum size. It also exerts some control over the alignment of items when they overflow the line.
`maxHeight`	`number \| string`	-
	Use numbers for pixels: `maxHeight={100}` and strings for percentages: `maxHeight="100%"`.
`maxWidth`	`number \| string`	-
	Use numbers for pixels: `maxWidth={100}` and strings for percentages: `maxWidth="100%"`.
`minHeight`	`number \| string`	-
	Use numbers for pixels: `minHeight={100}` and strings for percentages: `minHeight="100%"`.
`minWidth`	`number \| string`	-
	Use numbers for pixels: `minWidth={100}` and strings for percentages: `minWidth="100%"`.
`overflow`	`"visible" \| "hidden" \| "scroll" \| "scrollX" \| "scrollY" \| "auto"`	-
	Defines how to handle content that extends beyond the Flex container.
`ref`	`HTMLDivElement`	-
	Ref that is forwarded to the underlying div element.
`width`	`number \| string`	-
	Use numbers for pixels: `width={100}` and strings for percentages: `width="100%"`.
`wrap`	`boolean`	-
	By default, flex items will all try to fit onto one line. You can change that and allow the items to wrap onto multiple lines, from top to bottom.

Accessibility

Subcomponents

Flex.Item

Use Flex.Item within a Flex container for more precise control over the child element. Flex children that are not explicitly wrapped in Flex.Item will be wrapped in the the component automatically to apply gap spacing.

Flex.Item Props

Flex.Item subcomponent props
Name	Type	Default
`alignSelf`	`"auto" \| "start" \| "end" \| "center" \| "baseline" \| "stretch"`	-
	Allows the default alignment (or the one specified by `align-items`) to be overridden for the individual flex item.
`children`	`React.Node`	-
`dataTestId`	`string`	-
	Used to identify the element for testing purposes.
`flex`	`"grow" \| "shrink" \| "none"`	`"shrink"`
	Defines how the flex item will be sized. `"grow"`, equivalent to `"flex: 1 1 auto"`, will size Flex.Item relative to its parent, growing and shrinking based on available space. `"shrink"`, equivalent to `"flex: 0 1 auto"` (the browser default), allows Flex.Item to shrink if compressed but not grow if given extra space. Finally, `"none"`, equivalent to `"flex: 0 0 auto"`, preserves Flex.Item's size based on child content regardless of its container's size.
`flexBasis`	`string \| number`	-
	Defines the initial main size of the flex item. Use numbers for pixels: `flexBasis={100}` and strings for other units: `flexBasis="100vh"`.
`maxWidth`	`number \| string`	-
	Use numbers for pixels: `maxWidth={100}` and strings for percentages: `maxWidth="100%"`.
`minWidth`	`number \| string`	-
	Use numbers for pixels: `minWidth={100}` and strings for percentages: `minWidth="100%"`. Can be used to fix overflowing children; see the example to learn more.
`ref`	`HTMLDivElement`	-
	Ref that is forwarded to the underlying div element.

Variants

Flex Layout

Flex is strictly for flex layouts. If you're new to flex layout, please read the excellent CSS-Tricks guide to flexbox for a great introduction. Also check out the entertaining Flexbox Froggy game for a fun way to get comfortable with flexbox properties.

alignItems="start", justifyContent="start"

alignItems="start", justifyContent="end"

alignItems="start", justifyContent="center"

alignItems="start", justifyContent="between"

alignItems="start", justifyContent="around"

alignItems="end", justifyContent="start"

alignItems="end", justifyContent="end"

alignItems="end", justifyContent="center"

alignItems="end", justifyContent="between"

alignItems="end", justifyContent="around"

alignItems="center", justifyContent="start"

alignItems="center", justifyContent="end"

alignItems="center", justifyContent="center"

alignItems="center", justifyContent="between"

alignItems="center", justifyContent="around"

alignItems="baseline", justifyContent="start"

alignItems="baseline", justifyContent="end"

alignItems="baseline", justifyContent="center"

alignItems="baseline", justifyContent="between"

alignItems="baseline", justifyContent="around"

alignItems="stretch", justifyContent="start"

alignItems="stretch", justifyContent="end"

alignItems="stretch", justifyContent="center"

alignItems="stretch", justifyContent="between"

alignItems="stretch", justifyContent="around"

Gap

Flex's gap prop determines spacing between children. Use a single number for equal row and column spacing, or an object to specify different spacing for each direction. For example, use gap={{ row: 2, column: 4 }} for different spacing between items in rows and columns (regardless of the specified direction). Or use the gap={3} shorthand for equal spacing for rows and columns.

import { Box, Flex, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex direction="column" gap={6}>
        <Flex direction="column" gap={2}>
          <Text>Equal vertical/horizontal spacing</Text>
          <Box borderStyle="sm" padding={2} rounding={3} width={150}>
            <Flex alignItems="center" gap={4} wrap>
              {[1, 2, 3, 4, 5, 6].map((x) => (
                <Box key={`equalGap ${x}`} color="selected" width={50}>
                  <Text color="light">Item {x}</Text>
                </Box>
              ))}
            </Flex>
          </Box>
        </Flex>
        <Flex direction="column" gap={2}>
          <Text>Different vertical/horizontal spacing</Text>
          <Box borderStyle="sm" padding={2} rounding={3} width={150}>
            <Flex alignItems="center" gap={{ row: 2, column: 8 }} wrap>
              {[1, 2, 3, 4, 5, 6].map((x) => (
                <Box key={`diffGap${x}`} color="selected" width={50}>
                  <Text color="light">Item {x}</Text>
                </Box>
              ))}
            </Flex>
          </Box>
        </Flex>
      </Flex>
    </Flex>
  );
}

Flex makes flexbox layouts with equally-spaced children a snap!

import { Box, Flex, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex alignItems="center" height="100%" justifyContent="center">
      <Box borderStyle="sm" paddingX={2} paddingY={3} rounding={3} width={130}>
        <Flex alignItems="center" direction="column" gap={4}>
          <Text>Menu Item 1</Text>
          <Text>Menu Item 2</Text>
          <Text>Menu Item 3</Text>
        </Flex>
      </Box>
    </Flex>
  );
}

Applying flex properties to children

When using the gap prop, Flex wraps each child in a Flex.Item sub-component. If one or more of those children need specific flex properties, you can use Flex.Item directly.

import { Box, Button, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box paddingX={2} paddingY={2} width="100%">
        <Flex alignItems="center" gap={4}>
          <Button text="Button 1" />
          <Flex.Item flex="grow">
            <Button text="Button 2" />
          </Flex.Item>
          <Button text="Button 3" />
        </Flex>
      </Box>
    </Flex>
  );
}

Initial item width using flexBasis

If an item needs a different width in the flex layout than the content would otherwise indicate, flexBasis can be used.

import { Flex, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex alignItems="center" gap={4}>
        <Flex.Item flexBasis={200}>
          <Text>Some text</Text>
        </Flex.Item>
        <Text>Some text</Text>
        <Flex.Item flexBasis="10em">
          <Text>
            Some really really really really really really really long text
          </Text>
        </Flex.Item>
      </Flex>
    </Flex>
  );
}

Overflowing children and minWidth

Extra-wide children can sometimes overflow the Flex parent container, breaking the layout (and skipping truncation, if applicable).
To fix this, simply wrap the wide child in Flex.Item with minWidth={0}. Voila!

For more info, check out this very helpful blog post.

import { Badge, Box, Flex, Icon, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box padding={3} rounding={3}>
        <Flex alignItems="center" gap={3}>
          <Icon accessibilityLabel="Private" icon="lock" />
          <Flex.Item minWidth={0}>
            <Text lineClamp={2}>
              Some really long title text that just keeps going and going and
              going and going and going and going and going and going and going
              and going and going and going and going and going and going and
              going
            </Text>
          </Flex.Item>
          <Badge text="Try it out!" />
        </Flex>
      </Box>
    </Flex>
  );
}

Component quality checklist

Component quality checklist
Quality item	Status	Status description
Figma Library		Component is not currently available in Figma.
Responsive Web	Ready	Component responds to changing viewport sizes in web and mobile web.

Internal documentation

PDocs available

Edit page on GitHub