Grid

A flex-based horizontal grid system used to build layouts.

<Grid gutter="space30">
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">Instant Provisioning</Heading>
      <Paragraph>The API and the Console allow you to search and provision local, toll-free, or mobile numbers by capability, geography, prefix or keyword.</Paragraph>
    </Card>
  </Column>
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">Vast Inventory</Heading>
      <Paragraph>Twilio maintains phone number inventory at a rate of 50 times the quantity provisioned daily for over 600 area codes and prefixes.</Paragraph>
    </Card>
  </Column>
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">Quality Screening</Heading>
      <Paragraph>Every phone number in the inventory passes a rigorous 60-day screening process to verify capabilities and test for unwanted call traffic.</Paragraph>
    </Card>
  </Column>
</Grid>

Guidelines

The grid component controls the visual layout and spacing between elements on a page or in containers.

About Grid

Grid creates organized and consistent product layouts, by providing a standard for positioning elements. Grid speeds up the designer-to-developer workflow by improving the consistency of design implementations. Use a Grid to layout and align content by applying standard spacing between elements on a page or within a component.

The standard desktop grid has 24-pixel gutters and can support up to 12 columns. The outside gutters are removed from the overall width of the grid.

Grid is built using the Flex component and is responsive. Grid column widths grow and shrink based on the parent element width.

Examples

Equal column widths

Use Column, which is a child component of Grid, to lay out equal-sized content, such as a feed of cards.

<Grid gutter="space30">
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">Instant Provisioning</Heading>
      <Paragraph>The API and the Console allow you to search and provision local, toll-free, or mobile numbers by capability, geography, prefix or keyword.</Paragraph>
    </Card>
  </Column>
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">Vast Inventory</Heading>
      <Paragraph>Twilio maintains phone number inventory at a rate of 50 times the quantity provisioned daily for over 600 area codes and prefixes.</Paragraph>
    </Card>
  </Column>
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">Quality Screening</Heading>
      <Paragraph>Every phone number in the inventory passes a rigorous 60-day screening process to verify capabilities and test for unwanted call traffic.</Paragraph>
    </Card>
  </Column>
</Grid>

Unequal column widths, using column span

Use the span prop to allow content to span multiple columns. Span defines how many columns you want the width of your content to take up out of a 12-column grid. The value of span becomes the numerator while 12 is the denominator, which gives us a percentage width value for each column. The default span is 1 column width.

In our example we're setting one column to equal 8 of the 12 columns (span={8}), and the other to be 4 of the 12 columns (span={4}).

<Grid gutter="space30">
  <Column span={8}>
    <Heading as="h4" variant="heading40">Getting Started with Parse</Heading>
    <Paragraph>
      Use SendGrid to make your email a two-way street. The Parse Webhook is a powerful tool that can take incoming email for your domain or subdomain and direct it to your application. The possibilities of this are endless!
    </Paragraph>
    <Heading as="h4" variant="heading40">Your Email Funnel</Heading>
    <Paragraph>
      Expert Insights analyzes each layer of your email funnel to determine leakage points (such as blocked emails) and opportunities to improve deliverability and engagement.
    </Paragraph>
  </Column>
  <Column span={4}>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">Expert Insights</Heading>
      <Paragraph>Send better email with Expert Insights. Our detailed monthly reports with expert recommendations will give you deeper visibility into the health and performance of your email program.</Paragraph>
      <Button>Add to Plan</Button>
    </Card>
  </Column>
</Grid>

(information)

An important note about span and offset props

When using span or offset, base your layout off a 12-column grid. For example, if you want to have two columns with one spanning twice as much as the other, then one column would span=8 and the other would span=4.

Offset column

Use offset to push a column to the right by a certain number of columns. For example, a layout with centered columns.

<Grid gutter="space30">
  <Column span={8} offset={2}>
    <Card padding="space70">
      <Text as="div" textAlign="center">
        <Heading as="h4" variant="heading40">Create your first Signup Form</Heading>
        <Paragraph>Create and share a form to capture new signups and add them directly to your Contacts. You’ll grow your list the right way, knowing each new contact has opted in to receive your content.</Paragraph>
        <Button>Create a Signup Form</Button>
      </Text>
    </Card>
  </Column>
</Grid>

Equal column heights

Set equalColumnHeights on a grid container and all columns in a single row will share the height of the tallest column.

This can be useful when trying to visually align Cards where their content is variable.

When columns have equal heights, a single child element will stretch to the height of the column. You may still need to control the width of that child though.

<Grid gutter="space30" equalColumnHeights>
  <Column span={4}>
    <Card padding="space70">
      <Heading as="h2" variant="heading20">
        Why use Paste?
      </Heading>
      <Paragraph marginBottom="space0">
        Paste helps you rapidly prototype, and ship great, inclusive customer experiences. It makes it easy to
        do the right thing, cheaply.
      </Paragraph>
    </Card>
  </Column>
  <Column span={4}>
    <Card padding="space70">
      <Heading as="h2" variant="heading20">
        Inclusive by default
      </Heading>
      <Paragraph marginBottom="space0">
        Paste meets WCAG 2.1 AA standards in the design and development of our components, making it even easier
        to build accessibly.
      </Paragraph>
    </Card>
  </Column>
  <Column span={4}>
    <Card padding="space70">
      <Heading as="h2" variant="heading20">
        Get up and running
      </Heading>
      <Paragraph marginBottom="space0">
        Whether you’re a designer or developer, setting up Paste is easy and only takes a few minutes!
      </Paragraph>
    </Card>
  </Column>
</Grid>

Stacked columns in a vertical layout

Use the vertical prop to stack columns vertically instead of horizontally. The vertical prop can work along with theme breakpoints, so your grid can be vertical on different viewports. For example to have your grid vertical on mobile and not tablet or desktop viewports, use vertical={[true, false, false]}. For a visual example, see the Storybook example and resize the browser.

<Grid gutter="space30" vertical>
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">Web API</Heading>
      <Paragraph>The fastest, most flexible way to send email using languages like Node.js, Ruby, C#, and more.</Paragraph>
      <Button>Choose</Button>
    </Card>
  </Column>
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">SMTP Relay</Heading>
      <Paragraph>The easiest way to send email. It only requires modifying your application's SMTP configuration.</Paragraph>
      <Button>Choose</Button>
    </Card>
  </Column>
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">What's new at Twilio</Heading>
      <Paragraph>Check out our newest product releases on the Twilio Changelog.</Paragraph>
      <Button>Changelog</Button>
    </Card>
  </Column>
</Grid>

Nested Grids

A Grid can be nested inside another Grid. For example, you can split a column into multiple smaller columns in order to stack the outer Grid in a responsive view but not the inner Grid.

<Grid gutter="space30" vertical>
  <Column>
    <Grid gutter="space30">
      <Column>
        <Card padding="space70">
          <Heading as="h4" variant="heading40">Getting Started</Heading>
          <Paragraph>To get started with Phone Numbers, check out our Getting Started Guide.</Paragraph>
        </Card>
      </Column>
      <Column>
        <Card padding="space70">
          <Heading as="h4" variant="heading40">About Web API</Heading>
          <Paragraph>The fastest, most flexible way to send email using languages like Node.js, Ruby, C#, and more.</Paragraph>
        </Card>
      </Column>
    </Grid>
  </Column>
  <Column>
    <Card padding="space70">
      <Heading as="h4" variant="heading40">SMTP Relay</Heading>
      <Paragraph>The easiest way to send email. It only requires modifying your application's SMTP configuration.</Paragraph>
    </Card>
  </Column>
  <Column>
    <Grid gutter="space30">
      <Column>
        <Card padding="space70">
          <Heading as="h4" variant="heading40">About Phone Numbers</Heading>
          <Paragraph>Programmable phone numbers are a core part of Twilio’s platform, enabling you to receive SMS, MMS, and phone calls.</Paragraph>
        </Card>
      </Column>
      <Column>
        <Card padding="space70">
          <Heading as="h4" variant="heading40">Messaging Services</Heading>
          <Paragraph>Messaging Services allow you to organize your messages and enable specific features for groups of messages.</Paragraph>
        </Card>
      </Column>
    </Grid>
  </Column>
</Grid>

Responsive columns

Grid column span, offset, and gutter props accept responsive values, allowing them to be changed on theme breakpoints. For example, setting span={[6, 8, 2] } on a Column will instruct the column to span 6 columns of the grid at the first breakpoint, 8 columns at the second, and 2 columns at the third breakpoint. Check out the examples below and resize the browser to see the responsive values in action.

When creating responsive layouts with the Grid, it is important to remember to control the vertical prop accordingly. At the breakpoints you wish to stack the columns, set vertical to equal true. This will apply the column gutters vertically, rather than horizontally.

Responsive column offset and span

<Grid gutter="space20" vertical={[true, false, false]}>
    <Column span={[12, 6, 6]} offset={[0, 2, 2]}>
      <Box backgroundColor="colorBackgroundPrimaryWeaker" fontSize="fontSize100" height="size40" display="flex" justifyContent="center" alignItems="center">
        A
      </Box>
    </Column>
    <Column span={4}>
      <Box backgroundColor="colorBackgroundPrimaryWeak" fontSize="fontSize100" height="size40" display="flex" justifyContent="center" alignItems="center">
        B
      </Box>
    </Column>
</Grid>

Responsive column gutters

<Grid gutter={['space20', 'space60', 'space90']} vertical={[true, true, false]}>
    <Column>
      <Box backgroundColor="colorBackgroundPrimaryWeakest" fontSize="fontSize100" height="size40" display="flex" justifyContent="center" alignItems="center">
        A
      </Box>
    </Column>
    <Column>
      <Box backgroundColor="colorBackgroundPrimaryWeaker" fontSize="fontSize100" height="size40" display="flex" justifyContent="center" alignItems="center">
        B
      </Box>
    </Column>
    <Column>
      <Box backgroundColor="colorBackgroundPrimaryWeak" fontSize="fontSize100" height="size40" display="flex" justifyContent="center" alignItems="center">
        C
      </Box>
    </Column>
</Grid>

Composition Notes

Grid can be used to compose various types of layouts ranging from whole application pages and views down to individual component layouts.

(information)

Gutter sizing

For spacing content in a layout wider than 1440 pixels, we recommend using a 24-pixel gutter. Use $space-40 to get a 24-pixel gutter.

For spacing content in a layout narrower than 1440 pixels, we recommend using a 16-pixel gutter. Use $space-30 to get a 16-pixel gutter.

Basic page layout

Let's look at a common use case where we need to layout a page with a sidebar and a grid within the page content area.

<Card padding="space70">
  <Grid gutter="space30">
    <Column span={3}>
      <Box backgroundColor="colorBackground" padding="space70" borderRadius="borderRadius20">
        <Heading as="h4" variant="heading40">Dashboard</Heading>
        <Box marginBottom="space20">
          <Anchor href="#">Billing</Anchor>
        </Box>
        <Box marginBottom="space20">
          <Anchor href="#">Usage</Anchor>
        </Box>
        <Box marginBottom="space20">
          <Anchor href="#">Settings</Anchor>
        </Box>
      </Box>
    </Column>
    <Column span={9}>
      <Box marginBottom="space50">
        <Card>
          <Heading as="h4" variant="heading40">Project Info</Heading>
          <Text as="p" marginBottom="space0" color="colorTextWeak">BALANCE</Text>
          <Text as="p" marginBottom="space50" color="colorTextSuccess" fontWeight="fontWeightBold">$33.28</Text>
          <Text as="p" marginBottom="space0" color="colorTextWeak">REFERRAL PROGRAM</Text>
          <Text as="p" marginBottom="space0">Refer your network to Twilio — give $10, get $10.</Text>
        </Card>
      </Box>
      <Grid gutter="space30">
        <Column>
          <Card>
            <Heading as="h4" variant="heading40">What's new at Twilio</Heading>
            <Paragraph>Check out our newest product releases on the Twilio Changelog.</Paragraph>
            <Button>Changelog</Button>
          </Card>
        </Column>
        <Column>
          <Card>
            <Heading as="h4" variant="heading40">Twilio Docs</Heading>
            <Paragraph>Dig into our API reference documentation and quickstarts. You're covered with everything from SDKs in your favorite languages to sample apps for web, iOS, and Android.</Paragraph>
            <Button variant="secondary">Explore the Docs</Button>
          </Card>
        </Column>
      </Grid>
    </Column>
  </Grid>
</Card>

Responsive page layout

Grid can also be used for responsive layouts.

You can determine what size columns should be based on the breakpoints set on a theme. See the Storybook example
Grid columns can also stack based on theme breakpoints. See the Storybook example

Component layout

Grids can also be used for layouts within other components. For example, we can set up our card content to include 2 columns.

<Card padding="space70">
  <Grid gutter="space30">
    <Column span={2}>
      <TwilioIcon color={TWILIO_RED} display="block" size={65} />
    </Column>
    <Column span={10}>
      <Heading as="h4" variant="heading40">What's new at Twilio</Heading>
      <Paragraph>Check out our newest product releases on the Twilio Changelog.</Paragraph>
      <Button>Changelog</Button>
    </Column>
  </Grid>
</Card>

When to use Grid

Use Grid whenever you need to layout or align content on a page or within a component. Grid should also be used for responsive page layouts. Since the grid is sized to the full width of its parent container, you may not want to use it for fixed width columns in a variable width container.

4 Column Card

8 Column Card

Do

Base the Column span and offset on a 12-column layout.

Card content

Don't

Don’t use more than 12 columns within Grid.

Card content

Do

Use Grid to align content to the right or left side of a page layout.

Unnecessary HTML elements. Use Box instead.

Don't

Don’t use Grid with only one full-width column of content. This causes unnecessary elements. Box is what you’re looking for here.

Card content

Do

Use Grid to lay out UI elements into consistent columns.

Card content

Don't

Don’t let columns grow too small. Gutters should never be wider than columns.