Grid

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

Status
beta
Version
0.2.48
Sources
Abstract
Install
yarn add @twilio-paste/grid — or — yarn add @twilio-paste/core

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.

Instant Provisioning

The API and the Console allow you to search and provision local, toll-free, or mobile numbers by capability, geography, prefix or keyword.

Vast Inventory

Twilio maintains phone number inventory at a rate of 50 times the quantity provisioned daily for over 600 area codes and prefixes.

Quality Screening

Every phone number in the inventory passes a rigorous 60-day screening process to verify capabilities and test for unwanted call traffic.

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

Getting Started with Parse

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!

Your Email Funnel

Expert Insights analyzes each layer of your email funnel to determine leakage points (such as blocked emails) and opportunities to improve deliverability and engagement.

Expert Insights

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.

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.

Create your first Signup Form

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.

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.

Web API

The fastest, most flexible way to send email using languages like Node.js, Ruby, C#, and more.

SMTP Relay

The easiest way to send email. It only requires modifying your application's SMTP configuration.

What's new at Twilio

Check out our newest product releases on the Twilio Changelog.

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.

Getting Started

To get started with Phone Numbers, check out our Getting Started Guide.

About Web API

The fastest, most flexible way to send email using languages like Node.js, Ruby, C#, and more.

SMTP Relay

The easiest way to send email. It only requires modifying your application's SMTP configuration.

About Phone Numbers

Programmable phone numbers are a core part of Twilio’s platform, enabling you to receive SMS, MMS, and phone calls.

Messaging Services

Messaging Services allow you to organize your messages and enable specific features for groups of messages.

Responsive columns#

Grid column span and offset props can be changed based on the theme breakpoints. Both span and offset can accept responsive values, for example span={[6, 8, 2] }. This would set a columns span to be 6 columns wide on mobile, 8 columns wide on tablet, and 2 columns wide on desktop. The offset prop works in a similar fashion. For a visual example, see the Storybook example and resize the browser.

Composition Notes#

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

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.

Project Info

BALANCE

$33.28

REFERRAL PROGRAM

Refer your network to Twilio — give $10, get $10.

What's new at Twilio

Check out our newest product releases on the Twilio Changelog.

Twilio Docs

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.

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.

What's new at Twilio

Check out our newest product releases on the Twilio Changelog.

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

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

Card content

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

Card content

Card content

Card content

Do

Use Grid to lay out UI elements into consistent columns.

Card content

Card content

Card content

Don't

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


Usage Guide#

API#

Installation#

yarn add @twilio-paste/grid - or - yarn add @twilio-paste/core

Usage#

import {Grid, Column} from '@twilio-paste/grid';
const Component = () => (
<Grid>
<Column>Foo</Column>
</Grid>
);

Grid Props#

PropTypeDescriptionDefault
gutter?ResponsiveValue<keyof ThemeShape['space']>Sets the spacing on both sides of a Column. Use a spacing token that represents half of the total space you need between 2 Columns.
vertical?boolean, ResponsiveValue<boolean>Stacks the Columns

Column Props#

PropTypeDescriptionDefault
span?number, ResponsiveValue<number>Sets the width of Columns (how many columns a column can span)
offset?number, ResponsiveValue<number>Sets the left margin of a Column (how many columns a column is offset)

Sketch#

Add Grid symbols from the “Paste components” project to your own artboards to help you align content.

Additionally, each Paste container component (e.g., Card, Modal) symbol in Sketch has an invisible grid symbol named “📐 Grid” that you can override with visible grid symbols.

We use grid symbols instead of Sketch Layout Settings for two reasons:

  1. Resizing a symbol better represents the behavior of a fluid grid in a responsive layout. You might be designing for multiple screen widths in a single Sketch file. Sketch Layout Settings, however, restricts you to a single setting of grid width, column width, gutter width, and number of columns for each file.
  2. Symbols allow you to place a grid within a component or container on an artboard, whereas Sketch Layout Settings can be applied only to a whole artboard.

Support

If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.

Contributing

The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.