Grid
Two-dimensional CSS Grid layout component for complex grid-based layouts with rows and columns
Grid is a two-dimensional CSS Grid layout component for complex grid-based layouts. It extends Box, inheriting all Box capabilities (padding, elevation, rounding, self-alignment, and polymorphic as prop).
Use Grid when: You need explicit two-dimensional layouts with rows and columns, named grid areas, or responsive auto-fill patterns.
Installation
npm install --save @godaddy/antaresProps
The Grid component accepts the following props:
display?"grid" | "inline-grid" | undefined'grid'The display property for the grid container.
areas?string[] | undefined—Defines named grid areas. Eg. ['header header', 'sidebar main']
columns?string | undefined—Defines the columns of the grid. Eg. '1fr 2fr' or 'repeat(3, 1fr)'
rows?string | undefined—Defines the rows of the grid. Eg. 'auto 1fr auto'
autoColumns?string | undefined—The size of implicitly-created columns.
autoRows?string | undefined—The size of implicitly-created rows.
autoFlow?"row" | "column" | "dense" | "row dense" | "column dense" | (string & {}) | undefined—Controls how auto-placed items are flowed into the grid.
as?(ElementType & C) | undefined'div'Polymorphic element type.
padding?Spacing | Spacing[] | undefined—Padding on all sides. Accepts single value or array.
inlinePadding?Spacing | Spacing[] | undefined—Padding on inline (horizontal) direction.
inlinePaddingStart?Spacing | undefined—Padding on inline start (left in LTR).
inlinePaddingEnd?Spacing | undefined—Padding on inline end (right in LTR).
blockPadding?Spacing | Spacing[] | undefined—Padding on block (vertical) direction.
blockPaddingStart?Spacing | undefined—Padding on block start (top).
blockPaddingEnd?Spacing | undefined—Padding on block end (bottom).
elevation?"base" | "card" | "raised" | "overlay" | undefined—Elevation levels for visual depth.
rounding?Rounding | undefined—Rounding values for border radius.
alignSelf?"center" | (string & {}) | "auto" | "normal" | "start" | "end" | "flex-start" | "flex-end" | "self-start" | "self-end" | "stretch" | undefined—In Flex/Grid layout. Cross-axis alignment within flex/grid container.
justifySelf?"center" | (string & {}) | "auto" | "normal" | "start" | "end" | "flex-start" | "flex-end" | "self-start" | "self-end" | "stretch" | "left" | "right" | undefined—In Flex/Grid layout. Main-axis alignment within flex/grid container.
order?string | number | undefined—In Flex/Grid layout. Layout order within flex/grid container.
flex?string | number | undefined—In Flex/Grid layout. Flex shorthand for grow, shrink, and basis.
flexGrow?string | number | undefined—In Flex/Grid layout. How much the item will grow relative to siblings.
flexShrink?string | number | undefined—In Flex/Grid layout. How much the item will shrink relative to siblings.
flexBasis?string | undefined—In Flex/Grid layout. Initial main size before growing/shrinking.
gridArea?string | undefined—In Flex/Grid layout. Named grid area for placement.
gridColumnStart?string | undefined—In Flex/Grid layout. Grid column start line.
gridColumnEnd?string | undefined—In Flex/Grid layout. Grid column end line.
gridRowStart?string | undefined—In Flex/Grid layout. Grid row start line.
gridRowEnd?string | undefined—In Flex/Grid layout. Grid row end line.
justifyContent?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "space-around" | "space-between" | "space-evenly" | undefined—The distribution of space around children along the main axis in flex or inline axis in grid
alignContent?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "space-around" | "space-between" | "space-evenly" | "baseline" | undefined—The distribution of space around children along the cross axis in flex or block axis in grid
justifyItems?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "legacy" | undefined—Defines the default justify-self for all children in a grid container.
alignItems?"center" | (string & {}) | "normal" | "start" | "end" | "stretch" | "baseline" | undefined—Sets the align-self property for each child.
gap?Spacing | Spacing[] | undefined—The gap between children.
columnGap?Spacing | undefined—The gap between columns.
rowGap?Spacing | undefined—The gap between rows.
Scale Sizes
We use the same scale sizes as the Box component. For more information, see the Box component documentation.
Examples
Default
Basic 3-column grid layout with gap.
import { Grid, Flex, type GridProps } from '@godaddy/antares';export function DefaultExample(props: GridProps) { return ( <Grid columns="repeat(3, 1fr)" gap="sm" {...props}> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 1 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 2 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 3 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 4 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 5 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 6 </Flex> </Grid> );}Columns
The columns prop defines grid column tracks using CSS grid-template-columns syntax.
import { Grid, Flex } from '@godaddy/antares';export function ColumnsExample() { return ( <Flex direction="column" gap="lg"> <Flex direction="column" gap="sm"> <Flex as="strong">columns: repeat(2, 1fr)</Flex> <Grid columns="repeat(2, 1fr)" gap="sm"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 1 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 2 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 3 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 4 </Flex> </Grid> </Flex> <Flex direction="column" gap="sm"> <Flex as="strong">columns: 1fr 2fr 1fr</Flex> <Grid columns="1fr 2fr 1fr" gap="sm"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Narrow </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Wide </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Narrow </Flex> </Grid> </Flex> <Flex direction="column" gap="sm"> <Flex as="strong">columns: auto 1fr auto</Flex> <Grid columns="auto 1fr auto" gap="sm"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Auto </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Flexible </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Auto </Flex> </Grid> </Flex> </Flex> );}Gap
The gap prop controls spacing between grid cells. Use rowGap and columnGap for independent control.
import { Grid, Flex } from '@godaddy/antares';export function GapExample() { return ( <Flex direction="column" gap="lg"> <Flex direction="column" gap="sm"> <Flex as="strong">gap: xs</Flex> <Grid columns="repeat(3, 1fr)" gap="xs"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item </Flex> </Grid> </Flex> <Flex direction="column" gap="sm"> <Flex as="strong">gap: md</Flex> <Grid columns="repeat(3, 1fr)" gap="md"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item </Flex> </Grid> </Flex> <Flex direction="column" gap="sm"> <Flex as="strong">gap: xl</Flex> <Grid columns="repeat(3, 1fr)" gap="xl"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item </Flex> </Grid> </Flex> <Flex direction="column" gap="sm"> <Flex as="strong">rowGap: lg, columnGap: xs</Flex> <Grid columns="repeat(3, 1fr)" rowGap="lg" columnGap="xs"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 1 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 2 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 3 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 4 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 5 </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Item 6 </Flex> </Grid> </Flex> </Flex> );}Named Areas
Use areas to define named grid regions. Children use gridArea prop for placement.
import { Grid, Flex } from '@godaddy/antares';export function AreasExample() { return ( <Grid areas={['header header header', 'sidebar main main', 'footer footer footer']} columns="200px 1fr 1fr" rows="auto 1fr auto" gap="sm" style={{ height: '300px' }} > <Flex gridArea="header" padding="sm" style={{ background: '#c0c0c0' }}> Header </Flex> <Flex gridArea="sidebar" padding="sm" style={{ background: '#d0d0d0' }}> Sidebar </Flex> <Flex gridArea="main" padding="sm" style={{ background: '#e0e0e0' }}> Main Content </Flex> <Flex gridArea="footer" padding="sm" style={{ background: '#c0c0c0' }}> Footer </Flex> </Grid> );}Responsive Grid
Use CSS auto-fill and minmax() for responsive column counts without media queries.
import { Grid, Flex } from '@godaddy/antares';export function ResponsiveExample() { return ( <Grid columns="repeat(auto-fill, minmax(150px, 1fr))" gap="sm"> <Flex padding="md" style={{ background: '#e0e0e0' }}> Card 1 </Flex> <Flex padding="md" style={{ background: '#e0e0e0' }}> Card 2 </Flex> <Flex padding="md" style={{ background: '#e0e0e0' }}> Card 3 </Flex> <Flex padding="md" style={{ background: '#e0e0e0' }}> Card 4 </Flex> <Flex padding="md" style={{ background: '#e0e0e0' }}> Card 5 </Flex> <Flex padding="md" style={{ background: '#e0e0e0' }}> Card 6 </Flex> </Grid> );}Alignment
Use justifyItems and alignItems to control default alignment of all grid children.
import { Grid, Flex } from '@godaddy/antares';export function AlignmentExample() { return ( <Flex direction="column" gap="lg"> <Flex direction="column" gap="sm"> <Flex as="strong">justifyItems: center</Flex> <Grid columns="repeat(3, 1fr)" gap="sm" justifyItems="center" elevation="base"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Centered </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Centered </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Centered </Flex> </Grid> </Flex> <Flex direction="column" gap="sm"> <Flex as="strong">alignItems: center (with fixed row height)</Flex> <Grid columns="repeat(3, 1fr)" rows="100px" gap="sm" alignItems="center" elevation="base"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Centered </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Centered </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> Centered </Flex> </Grid> </Flex> <Flex direction="column" gap="sm"> <Flex as="strong">justifyItems: end, alignItems: end</Flex> <Grid columns="repeat(3, 1fr)" rows="80px" gap="sm" justifyItems="end" alignItems="end" elevation="base"> <Flex padding="sm" style={{ background: '#e0e0e0' }}> End </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> End </Flex> <Flex padding="sm" style={{ background: '#e0e0e0' }}> End </Flex> </Grid> </Flex> </Flex> );}Form Layout
A common two-column form pattern with auto-sized label column.
import { Grid, Flex } from '@godaddy/antares';export function FormExample() { return ( <Grid columns="auto 1fr" gap="md" alignItems="center" style={{ width: '400px' }}> <Flex as="label">Name</Flex> <Flex padding="sm" style={{ background: '#f5f5f5' }}> Input placeholder </Flex> <Flex as="label">Email</Flex> <Flex padding="sm" style={{ background: '#f5f5f5' }}> Input placeholder </Flex> <Flex as="label">Message</Flex> <Flex padding="sm" style={{ background: '#f5f5f5' }}> Textarea placeholder </Flex> </Grid> );}RTL Support
Grid uses CSS logical properties which automatically adapt to RTL layouts. Grid areas and alignment respect the document direction.
Grid vs Flex
| Use Case | Recommended |
|---|---|
| Single row/column of items | Flex |
| Two-dimensional layouts | Grid |
| Named layout regions | Grid |
| Auto-wrapping cards | Grid (auto-fill) |
| Navigation bars | Flex |
| Form layouts | Grid |