Flex

View source on GitHub
; Opens a new tab

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
Web:
Ready
iOS:
N/A
Android:
N/A
A11y:
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"
-

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 |}
-

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.

lgAlignItems
"start" | "end" | "center" | "baseline" | "stretch"
-

The alignItems style in lg or larger viewports. See the Screen size page to learn more about viewport breakpoints in web.

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

mdAlignItems
"start" | "end" | "center" | "baseline" | "stretch"
-

The alignItems style in md or larger viewports. See the Screen size page to learn more about viewport breakpoints in web.

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.

smAlignItems
"start" | "end" | "center" | "baseline" | "stretch"
-

The alignItems style in sm or larger viewports. See the Screen size page to learn more about viewport breakpoints in web.

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.

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.

justifyContent="start", alignItems="start"
justifyContent="start", alignItems="end"
justifyContent="start", alignItems="center"
justifyContent="start", alignItems="baseline"
justifyContent="start", alignItems="stretch"
justifyContent="end", alignItems="start"
justifyContent="end", alignItems="end"
justifyContent="end", alignItems="center"
justifyContent="end", alignItems="baseline"
justifyContent="end", alignItems="stretch"
justifyContent="center", alignItems="start"
justifyContent="center", alignItems="end"
justifyContent="center", alignItems="center"
justifyContent="center", alignItems="baseline"
justifyContent="center", alignItems="stretch"
justifyContent="between", alignItems="start"
justifyContent="between", alignItems="end"
justifyContent="between", alignItems="center"
justifyContent="between", alignItems="baseline"
justifyContent="between", alignItems="stretch"
justifyContent="around", alignItems="start"
justifyContent="around", alignItems="end"
justifyContent="around", alignItems="center"
justifyContent="around", alignItems="baseline"
justifyContent="around", alignItems="stretch"

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 { Flex, Box, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      width="100%"
      height="100%"
      justifyContent="center"
      alignItems="center"
    >
      <Flex gap={6} direction="column">
        <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}`} width={50} color="selected">
                  <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 width={50} color="selected" key={`diffGap${x}`}>
                  <Text color="light">Item {x}</Text>
                </Box>
              ))}
            </Flex>
          </Box>
        </Flex>
      </Flex>
    </Flex>
  );
}

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

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

export default function Example() {
  return (
    <Flex height="100%" alignItems="center" 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 { Flex, Box, Button } from 'gestalt';

export default function Example() {
  return (
    <Flex
      width="100%"
      height="100%"
      justifyContent="center"
      alignItems="center"
    >
      <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
      width="100%"
      height="100%"
      justifyContent="center"
      alignItems="center"
    >
      <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 { Flex, Box, Text, Icon, Badge } from 'gestalt';

export default function Example() {
  return (
    <Flex
      width="100%"
      height="100%"
      justifyContent="center"
      alignItems="center"
    >
      <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 is available in code for web and mobile web.
iOS
Component is not currently available in code for iOS.
Android
Component is not currently available in code for Android.
Edit page on GitHub
; Opens a new tab