Box

The Box component can be used for simple flex and grid layouts that have spacing between each item. This should be the go-to component for creating layouts or spacing items on the page.

Most of these examples are only available on desktop due to limited demo preview

Flex Example

The Box defaults to using display: flex, align-items: center, justify-content: center, padding: 1rem, and gap: 1rem.

The padding and gap can be configured globally by changing the core.$box-gap and core.$box-padding Sass variables.

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { type ReactElement } from "react";

export default function FlexExample(): ReactElement {
  return (
    <Box>
      {Array.from({ length: 20 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </Box>
  );
}

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { type ReactElement } from "react";

export default function FlexExample(): ReactElement {
  return (
    <Box>
      {Array.from({ length: 20 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </Box>
  );
}

Disable Flex Wrap

Enable the disableWrap prop to prevent line wrapping and instead attempt to shrink each item to fit on a single line.

Here is some long text that should be truncated

import { Box } from "@react-md/core/box/Box";
import { Typography } from "@react-md/core/typography/Typography";
import FavoriteIcon from "@react-md/material-icons/FavoriteIcon";
import { type ReactElement } from "react";

export default function DisableFlexWrap(): ReactElement {
  return (
    <Box style={{ width: "12rem" }} disableWrap>
      <FavoriteIcon />
      <Typography textOverflow="ellipsis">
        Here is some long text that should be truncated
      </Typography>
    </Box>
  );
}

import { Box } from "@react-md/core/box/Box";
import { Typography } from "@react-md/core/typography/Typography";
import FavoriteIcon from "@react-md/material-icons/FavoriteIcon";
import { type ReactElement } from "react";

export default function DisableFlexWrap(): ReactElement {
  return (
    <Box style={{ width: "12rem" }} disableWrap>
      <FavoriteIcon />
      <Typography textOverflow="ellipsis">
        Here is some long text that should be truncated
      </Typography>
    </Box>
  );
}

Additional Flex Options

The following flex options can be configured by props:

align - "start" | "center" | "end" | "stretch"
justify - "start" | "center" | "end" | "stretch" | "space-around" | "space-between" | "space-evenly"
fullWidth - apply width: 100%
disablePadding - do not apply the default padding
stacked - set flex-direction: column
reversed - set flex-direction: row-reverse or flex-direction: column-reverse when stacked is enabled

See the example below to see how these props can be used.

No Default Padding

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Stacked, Align Stretch, Full Width

Item 1

Item 2

Item 3

Item 4

Align Start

First

Second

Some additional content.

Reversed, Justify Space Between

First

Second

Some additional content.

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Divider } from "@react-md/core/divider/Divider";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

export default function AdditionalFlexOptions(): ReactElement {
  return (
    <>
      <Typography>No Default Padding</Typography>
      <Box disablePadding>
        {Array.from({ length: 8 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Typography>Stacked, Align Stretch, Full Width</Typography>
      <Box stacked align="stretch" fullWidth>
        {Array.from({ length: 4 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Divider />
      <Typography>Align Start</Typography>
      <Box align="start">
        <Card>
          <CardContent>First</CardContent>
        </Card>
        <Card>
          <CardContent>Second</CardContent>
          <CardContent>Some additional content.</CardContent>
        </Card>
      </Box>
      <Divider />
      <Typography>Reversed, Justify Space Between</Typography>
      <Box align="start" reversed justify="space-between">
        <Card>
          <CardContent>First</CardContent>
        </Card>
        <Card>
          <CardContent>Second</CardContent>
          <CardContent>Some additional content.</CardContent>
        </Card>
      </Box>
    </>
  );
}

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Divider } from "@react-md/core/divider/Divider";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

export default function AdditionalFlexOptions(): ReactElement {
  return (
    <>
      <Typography>No Default Padding</Typography>
      <Box disablePadding>
        {Array.from({ length: 8 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Typography>Stacked, Align Stretch, Full Width</Typography>
      <Box stacked align="stretch" fullWidth>
        {Array.from({ length: 4 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Divider />
      <Typography>Align Start</Typography>
      <Box align="start">
        <Card>
          <CardContent>First</CardContent>
        </Card>
        <Card>
          <CardContent>Second</CardContent>
          <CardContent>Some additional content.</CardContent>
        </Card>
      </Box>
      <Divider />
      <Typography>Reversed, Justify Space Between</Typography>
      <Box align="start" reversed justify="space-between">
        <Card>
          <CardContent>First</CardContent>
        </Card>
        <Card>
          <CardContent>Second</CardContent>
          <CardContent>Some additional content.</CardContent>
        </Card>
      </Box>
    </>
  );
}

Grid Example

Enable the grid prop to render equal width dynamic columns that will be at least 8rem wide.

The min width can be configured globally by changing the core.$box-item-min-size Sass variable.

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { type ReactElement } from "react";

export default function GridExample(): ReactElement {
  return (
    <Box grid>
      {Array.from({ length: 20 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </Box>
  );
}

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { type ReactElement } from "react";

export default function GridExample(): ReactElement {
  return (
    <Box grid>
      {Array.from({ length: 20 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </Box>
  );
}

Custom Grid Name

As the app grows it might be useful to define different grid variants that provide different min item size, gap, and/or padding. The variants can be configured by setting the core.$box-grids variable when @forward-ing or @use-ing @react-md/core. Each mapped name will be available as a gridName on the Box component.

Variant 1

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Variant 2

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Variant 3

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

import styles from "./CustomGridNameExample.module.scss";

export default function CustomGridNameExample(): ReactElement {
  return (
    <div className={styles.container}>
      <Typography>Variant 1</Typography>
      <BoxExample gridName="variant-1" />
      <Typography>Variant 2</Typography>
      <BoxExample gridName="variant-2" />
      <Typography>Variant 3</Typography>
      <BoxExample gridName="variant-3" />
    </div>
  );
}

function BoxExample({ gridName }: { gridName: string }): ReactElement {
  return (
    <Box grid gridName={gridName}>
      {Array.from({ length: 8 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </Box>
  );
}

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

import styles from "./CustomGridNameExample.module.scss";

export default function CustomGridNameExample(): ReactElement {
  return (
    <div className={styles.container}>
      <Typography>Variant 1</Typography>
      <BoxExample gridName="variant-1" />
      <Typography>Variant 2</Typography>
      <BoxExample gridName="variant-2" />
      <Typography>Variant 3</Typography>
      <BoxExample gridName="variant-3" />
    </div>
  );
}

function BoxExample({ gridName }: { gridName: string }): ReactElement {
  return (
    <Box grid gridName={gridName}>
      {Array.from({ length: 8 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </Box>
  );
}

@use "sass:map";
@use "@react-md/core" with (
  $box-grids: (
    variant-1: (
      min: 5rem,
    ),
    variant-2: (
      min: 7rem,
      gap: 0.5rem,
      padding: 2rem,
    ),
    variant-3: (
      min: 7rem,
      gap: 1.5rem,
      padding: 0,
    ),
  )
);

// this is only required for this demo. In your application, this should just be the normal:
// @include core.styles;
.container {
  :global {
    .rmd-box {
      @each $name, $values in core.$box-grids {
        @include core.box-custom-grid-class(
          "&--#{$name}",
          $min: map.get($values, min),
          $gap: map.get($values, gap),
          $padding: map.get($values, padding)
        );
      }
    }
  }
}

@use "sass:map";
@use "@react-md/core" with (
  $box-grids: (
    variant-1: (
      min: 5rem,
    ),
    variant-2: (
      min: 7rem,
      gap: 0.5rem,
      padding: 2rem,
    ),
    variant-3: (
      min: 7rem,
      gap: 1.5rem,
      padding: 0,
    ),
  )
);

// this is only required for this demo. In your application, this should just be the normal:
// @include core.styles;
.container {
  :global {
    .rmd-box {
      @each $name, $values in core.$box-grids {
        @include core.box-custom-grid-class(
          "&--#{$name}",
          $min: map.get($values, min),
          $gap: map.get($values, gap),
          $padding: map.get($values, padding)
        );
      }
    }
  }
}

Customizing Gap, Padding, and Min Item Size

The gap, padding, and min item size for part of the DOM using the core.box-set-var mixin or a custom class name on the Box component.

The gap and padding are also available for the flex version of the Box.

Item 1

Item 2

Item 3

Item 4

Item 5

Item 1

Item 2

Item 3

Item 4

Item 5

Item 1

Item 2

Item 3

Item 4

Item 5

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { type ReactElement } from "react";

import styles from "./CustomizingGapPaddingAndMinItemSize.module.scss";

export default function CustomizingGapPaddingAndMinItemSize(): ReactElement {
  return (
    <div className={styles.container}>
      <Box grid>
        <Cards />
      </Box>
      <Box grid className={styles.override}>
        <Cards />
      </Box>
      <Box grid>
        <Cards />
      </Box>
    </div>
  );
}

function Cards(): ReactElement {
  return (
    <>
      {Array.from({ length: 5 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </>
  );
}

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { type ReactElement } from "react";

import styles from "./CustomizingGapPaddingAndMinItemSize.module.scss";

export default function CustomizingGapPaddingAndMinItemSize(): ReactElement {
  return (
    <div className={styles.container}>
      <Box grid>
        <Cards />
      </Box>
      <Box grid className={styles.override}>
        <Cards />
      </Box>
      <Box grid>
        <Cards />
      </Box>
    </div>
  );
}

function Cards(): ReactElement {
  return (
    <>
      {Array.from({ length: 5 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </>
  );
}

@use "everything" as *;

.container {
  @include box-set-var(padding, 2rem);
  @include box-set-var(gap, 0.5rem);
  @include box-set-var(item-min-size, 5rem);
}

.override {
  @include box-set-var(item-min-size, 12rem);

  gap: 1.25rem;
  padding: 0.25rem;
}

@use "everything" as *;

.container {
  @include box-set-var(padding, 2rem);
  @include box-set-var(gap, 0.5rem);
  @include box-set-var(item-min-size, 5rem);
}

.override {
  @include box-set-var(item-min-size, 12rem);

  gap: 1.25rem;
  padding: 0.25rem;
}

Auto-fill Grid Columns

The grid defaults to using auto-fit but can be configured to auto-fill by setting gridColumns="fill". To help explain the difference between the two:

auto-fit - fill the entire width with columns and stretch columns to fill the remaining space
auto-fill - fill the entire width with columns and add empty columns to fill the remaining space

Try changing the ITEMS value below to see the difference.

auto-fit (default)

Item 1

Item 2

Item 3

auto-fill

Item 1

Item 2

Item 3

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

// Change this value to see the difference between fit and fill
const ITEMS = 3;

export default function AutoFillGridColumnsExample(): ReactElement {
  return (
    <>
      <Typography>auto-fit (default)</Typography>
      <Box grid gridColumns="fit">
        {Array.from({ length: ITEMS }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Typography>auto-fill</Typography>
      <Box grid gridColumns="fill">
        {Array.from({ length: ITEMS }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
    </>
  );
}

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

// Change this value to see the difference between fit and fill
const ITEMS = 3;

export default function AutoFillGridColumnsExample(): ReactElement {
  return (
    <>
      <Typography>auto-fit (default)</Typography>
      <Box grid gridColumns="fit">
        {Array.from({ length: ITEMS }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Typography>auto-fill</Typography>
      <Box grid gridColumns="fill">
        {Array.from({ length: ITEMS }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
    </>
  );
}

Custom Grid Columns

If a specific number of columns should be enforced, set the gridColumns prop to that number.

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { type ReactElement } from "react";

export default function CustomGridColumnsExample(): ReactElement {
  return (
    <Box grid gridColumns={4}>
      {Array.from({ length: 16 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </Box>
  );
}

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { type ReactElement } from "react";

export default function CustomGridColumnsExample(): ReactElement {
  return (
    <Box grid gridColumns={4}>
      {Array.from({ length: 16 }, (_, i) => (
        <Card key={i}>
          <CardContent>{`Item ${i + 1}`}</CardContent>
        </Card>
      ))}
    </Box>
  );
}

Grid Column Media Queries

The gridColumns prop also supports setting different column behavior based on the defined media queries:

phone - core.phone-media
tablet - core.tablet-media
desktop - core.desktop-media
largeDesktop - core.large-desktop-media

Each of the breakpoints can be "fit", "fill", or a number of columns.

Using desktop: "fit"

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { useAppSize } from "@react-md/core/media-queries/AppSizeProvider";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

export default function GridColumnMediaQueries(): ReactElement {
  return (
    <>
      <AppSize />
      <Box
        grid
        gridColumns={{
          phone: 1,
          tablet: "fill",
          desktop: "fit",
          largeDesktop: 6,
        }}
      >
        {Array.from({ length: 7 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
    </>
  );
}

function AppSize(): ReactElement {
  const appSize = useAppSize();
  let current: string;
  if (appSize.isPhone) {
    current = "phone: 1";
  } else if (appSize.isTablet) {
    current = 'tablet: "fill"';
  } else if (appSize.isLargeDesktop) {
    current = "largeDesktop: 6";
  } else {
    current = 'desktop: "fit"';
  }
  return <Typography>Using {current}</Typography>;
}

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { useAppSize } from "@react-md/core/media-queries/AppSizeProvider";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

export default function GridColumnMediaQueries(): ReactElement {
  return (
    <>
      <AppSize />
      <Box
        grid
        gridColumns={{
          phone: 1,
          tablet: "fill",
          desktop: "fit",
          largeDesktop: 6,
        }}
      >
        {Array.from({ length: 7 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
    </>
  );
}

function AppSize(): ReactElement {
  const appSize = useAppSize();
  let current: string;
  if (appSize.isPhone) {
    current = "phone: 1";
  } else if (appSize.isTablet) {
    current = 'tablet: "fill"';
  } else if (appSize.isLargeDesktop) {
    current = "largeDesktop: 6";
  } else {
    current = 'desktop: "fit"';
  }
  return <Typography>Using {current}</Typography>;
}

Grid Auto Rows

To create rows with an equal height, enable the gridAutoRows restrict the height through CSS. This is most useful when handling unknown sized items (like file uploads).

Check out the useFileUpload for another example using auto rows.

Auto Rows

"use client";

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Switch } from "@react-md/core/form/Switch";
import { objectFit } from "@react-md/core/objectFit";
import { useToggle } from "@react-md/core/useToggle";
import { cnb } from "cnbuilder";
import { type ReactElement } from "react";

import styles from "./GridAutoRowsExample.module.scss";

export default function GridAutoRowsExample(): ReactElement {
  const { toggled, toggle } = useToggle(true);
  return (
    <>
      <Switch label="Auto Rows" checked={toggled} onChange={toggle} />
      <Box
        align="stretch"
        grid
        gridColumns="fill"
        gridAutoRows={toggled}
        className={cnb(styles.container, toggled && styles.auto)}
      >
        {IMAGES.map((src) => (
          <Card key={src}>
            <CardContent>
              <img alt="" src={src} className={objectFit()} />
            </CardContent>
          </Card>
        ))}
      </Box>
    </>
  );
}

const IMAGES = [
  {
    id: "237",
    height: 300,
    width: 200,
  },
  {
    id: "232",
    height: 120,
    width: 340,
  },
  {
    id: "337",
    height: 100,
    width: 100,
  },
  {
    id: "137",
    height: 800,
    width: 800,
  },
  {
    id: "33",
    height: 300,
    width: 123,
  },
].map(
  ({ id, height, width }) =>
    `https://picsum.photos/id/${id}/${width}/${height}`,
);

"use client";

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Switch } from "@react-md/core/form/Switch";
import { objectFit } from "@react-md/core/objectFit";
import { useToggle } from "@react-md/core/useToggle";
import { cnb } from "cnbuilder";
import { type ReactElement } from "react";

import styles from "./GridAutoRowsExample.module.scss";

export default function GridAutoRowsExample(): ReactElement {
  const { toggled, toggle } = useToggle(true);
  return (
    <>
      <Switch label="Auto Rows" checked={toggled} onChange={toggle} />
      <Box
        align="stretch"
        grid
        gridColumns="fill"
        gridAutoRows={toggled}
        className={cnb(styles.container, toggled && styles.auto)}
      >
        {IMAGES.map((src) => (
          <Card key={src}>
            <CardContent>
              <img alt="" src={src} className={objectFit()} />
            </CardContent>
          </Card>
        ))}
      </Box>
    </>
  );
}

const IMAGES = [
  {
    id: "237",
    height: 300,
    width: 200,
  },
  {
    id: "232",
    height: 120,
    width: 340,
  },
  {
    id: "337",
    height: 100,
    width: 100,
  },
  {
    id: "137",
    height: 800,
    width: 800,
  },
  {
    id: "33",
    height: 300,
    width: 123,
  },
].map(
  ({ id, height, width }) =>
    `https://picsum.photos/id/${id}/${width}/${height}`,
);

@use "everything" as *;

$min-size: 15rem;

.container {
  @include box-set-var(item-min-size, $min-size);
}

.auto {
  @include box-set-var(auto-rows-height, $min-size * 2);

  // this is about the same since it is applied to the `Box` component
  // max-height: $min-size * 2;

  // the rows can have a min height by updating this variable
  // this is the default value
  @include box-set-var(item-min-height, $min-size);

  // a max height can be set as well which is useful when there
  // could only be one row of content. you'd probably want something
  // close to the `item-min-size` as another value
  // this is the default value
  @include box-set-var(row-max-height, 1fr);
}

@use "everything" as *;

$min-size: 15rem;

.container {
  @include box-set-var(item-min-size, $min-size);
}

.auto {
  @include box-set-var(auto-rows-height, $min-size * 2);

  // this is about the same since it is applied to the `Box` component
  // max-height: $min-size * 2;

  // the rows can have a min height by updating this variable
  // this is the default value
  @include box-set-var(item-min-height, $min-size);

  // a max height can be set as well which is useful when there
  // could only be one row of content. you'd probably want something
  // close to the `item-min-size` as another value
  // this is the default value
  @include box-set-var(row-max-height, 1fr);
}

Additional Grid Options

The following grid options can be configured by props:

align - "start" | "center" | "end" | "stretch"
fullWidth - apply width: 100%
disablePadding - do not apply the default padding

See the example below to see how these props can be used.

No Default Padding

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Align Stretch, Full Width

Item 1

Item 2

Item 3

Item 4

Align Start

First

Second

Some additional content.

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Divider } from "@react-md/core/divider/Divider";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

export default function AdditionalGridOptions(): ReactElement {
  return (
    <>
      <Typography>No Default Padding</Typography>
      <Box grid disablePadding>
        {Array.from({ length: 8 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Typography>Align Stretch, Full Width</Typography>
      <Box grid align="stretch" fullWidth>
        {Array.from({ length: 4 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Divider />
      <Typography>Align Start</Typography>
      <Box align="start" grid>
        <Card>
          <CardContent>First</CardContent>
        </Card>
        <Card>
          <CardContent>Second</CardContent>
          <CardContent>Some additional content.</CardContent>
        </Card>
      </Box>
    </>
  );
}

import { Box } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { CardContent } from "@react-md/core/card/CardContent";
import { Divider } from "@react-md/core/divider/Divider";
import { Typography } from "@react-md/core/typography/Typography";
import { type ReactElement } from "react";

export default function AdditionalGridOptions(): ReactElement {
  return (
    <>
      <Typography>No Default Padding</Typography>
      <Box grid disablePadding>
        {Array.from({ length: 8 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Typography>Align Stretch, Full Width</Typography>
      <Box grid align="stretch" fullWidth>
        {Array.from({ length: 4 }, (_, i) => (
          <Card key={i}>
            <CardContent>{`Item ${i + 1}`}</CardContent>
          </Card>
        ))}
      </Box>
      <Divider />
      <Typography>Align Start</Typography>
      <Box align="start" grid>
        <Card>
          <CardContent>First</CardContent>
        </Card>
        <Card>
          <CardContent>Second</CardContent>
          <CardContent>Some additional content.</CardContent>
        </Card>
      </Box>
    </>
  );
}

Material Grid Example

The material design grid system is defined as:

4 columns on mobile
8 columns on tablet
12 columns on desktop

The material grid is no longer supported out of the box (ha) anymore but can be re-created using the gridColumns prop and setting the grid-column CSS property on cells to span multiple columns.

Cell 1

Cell 2

Cell 3

Cell 4

Cell 5

Cell 6

Cell 7

Cell 8

Cell 9

Cell 10

Cell 11

Cell 12

Cell 1

Cell 2

Cell 3

Cell 4

Cell 5

Cell 6

Cell 1

Cell 2

Cell 3

Cell 4

Cell 5

Cell 6

Cell 7

Cell 8

import { Box } from "@react-md/core/box/Box";
import { type BoxGridBreakpointColumns } from "@react-md/core/box/styles";
import { Card } from "@react-md/core/card/Card";
import { cssUtils } from "@react-md/core/cssUtils";
import { type CSSProperties, type ReactElement } from "react";

const GRID_COLUMNS: BoxGridBreakpointColumns = {
  phone: 4,
  tablet: 8,
  desktop: 12,
};

export default function MaterialGridExample(): ReactElement {
  return (
    <>
      <Box grid gridColumns={GRID_COLUMNS} align="stretch">
        {Array.from({ length: 12 }, (_, i) => (
          <Cell key={i} index={i} />
        ))}
      </Box>
      <Box grid gridColumns={GRID_COLUMNS} align="stretch">
        {Array.from({ length: 6 }, (_, i) => (
          <Cell key={i} index={i} style={{ gridColumn: "span 2" }} />
        ))}
      </Box>
      <Box grid gridColumns={GRID_COLUMNS} align="stretch">
        {Array.from({ length: 8 }, (_, i) => (
          <Cell key={i} index={i} style={{ gridColumn: "span 3" }} />
        ))}
      </Box>
    </>
  );
}

interface CellProps {
  style?: CSSProperties;
  index: number;
}

function Cell({ index, style }: CellProps): ReactElement {
  return (
    <Card
      align="center"
      justify="center"
      style={{ minHeight: "4rem", ...style }}
      className={cssUtils({ textAlign: "center" })}
    >
      {`Cell ${index + 1}`}
    </Card>
  );
}

import { Box } from "@react-md/core/box/Box";
import { type BoxGridBreakpointColumns } from "@react-md/core/box/styles";
import { Card } from "@react-md/core/card/Card";
import { cssUtils } from "@react-md/core/cssUtils";
import { type CSSProperties, type ReactElement } from "react";

const GRID_COLUMNS: BoxGridBreakpointColumns = {
  phone: 4,
  tablet: 8,
  desktop: 12,
};

export default function MaterialGridExample(): ReactElement {
  return (
    <>
      <Box grid gridColumns={GRID_COLUMNS} align="stretch">
        {Array.from({ length: 12 }, (_, i) => (
          <Cell key={i} index={i} />
        ))}
      </Box>
      <Box grid gridColumns={GRID_COLUMNS} align="stretch">
        {Array.from({ length: 6 }, (_, i) => (
          <Cell key={i} index={i} style={{ gridColumn: "span 2" }} />
        ))}
      </Box>
      <Box grid gridColumns={GRID_COLUMNS} align="stretch">
        {Array.from({ length: 8 }, (_, i) => (
          <Cell key={i} index={i} style={{ gridColumn: "span 3" }} />
        ))}
      </Box>
    </>
  );
}

interface CellProps {
  style?: CSSProperties;
  index: number;
}

function Cell({ index, style }: CellProps): ReactElement {
  return (
    <Card
      align="center"
      justify="center"
      style={{ minHeight: "4rem", ...style }}
      className={cssUtils({ textAlign: "center" })}
    >
      {`Cell ${index + 1}`}
    </Card>
  );
}

Material Grid Customization

If the material grid system is actually still useful, it is recommended to create a few utility classes to help position grid items.

This is not natively supported by react-md since I've never needed to create layouts that could not be solved with the non-material design grid system.

Here's an example:

Cell 1

Cell 2

Cell 3

Cell 4

Cell 5

import { Box, type BoxProps } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { cnb } from "cnbuilder";
import { type CSSProperties, type ReactElement } from "react";

import styles from "./MaterialGridCustomizationExample.module.scss";

export default function MaterialGridCustomizationExample(): ReactElement {
  return (
    <MaterialGrid>
      <Card {...gridCell({ order: 2, className: styles.container })}>
        Cell 1
      </Card>
      <Card className={styles.container}>Cell 2</Card>
      <Card
        {...gridCell({
          span: { phone: 4, tablet: 3, desktop: 6 },
          className: styles.container,
        })}
      >
        Cell 3
      </Card>
      <Card
        {...gridCell({ offset: { tablet: 4 }, className: styles.container })}
      >
        Cell 4
      </Card>
      <Card className={styles.container}>Cell 5</Card>
    </MaterialGrid>
  );
}

function MaterialGrid(
  props: Omit<BoxProps, "grid" | "gridColumns">,
): ReactElement {
  return (
    <Box {...props} grid gridColumns={{ phone: 4, tablet: 8, desktop: 12 }} />
  );
}

type Breakpoint = "phone" | "tablet" | "desktop";
type CellIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
type Breakpoints = { [key in Breakpoint]?: CellIndex };
type ValueOrBreakpoints = CellIndex | Breakpoints;

declare module "react" {
  type CellProperty = "span" | "order" | "offset";
  type CellPropertyWithBreakpoint =
    | CellProperty
    | `${Breakpoint}-${CellProperty}`;

  type CellProperties = {
    [name in `--cell-${CellPropertyWithBreakpoint}`]?: string | number;
  };

  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
  interface CSSProperties extends CellProperties {}
}

const applyVar = (
  type: "span" | "order" | "offset",
  breakpoint: Breakpoint | "",
  value?: ValueOrBreakpoints,
  style?: CSSProperties,
): CSSProperties | undefined => {
  if (typeof value !== "string" && typeof value !== "number") {
    return style;
  }

  const name = breakpoint
    ? (`--cell-${breakpoint}-${type}` as const)
    : (`--cell-${type}` as const);
  return {
    ...style,
    [name]: value,
  };
};

const BREAKPOINTS = ["phone", "tablet", "desktop"] as const;

const applyVarGroup = (
  type: "span" | "order" | "offset",
  value?: ValueOrBreakpoints,
  style?: CSSProperties,
): CSSProperties | undefined => {
  let combinedStyle = applyVar(type, "", value, style);
  if (value && typeof value === "object") {
    for (const breakpoint of BREAKPOINTS) {
      combinedStyle = applyVar(
        type,
        breakpoint,
        value[breakpoint],
        combinedStyle,
      );
    }
  }
  return combinedStyle;
};

interface GridCellStyles {
  style?: CSSProperties;
  className?: string;
}

interface GridCellOptions extends GridCellStyles {
  span?: ValueOrBreakpoints;
  order?: ValueOrBreakpoints;
  offset?: ValueOrBreakpoints;
}

function gridCell(options: GridCellOptions): GridCellStyles {
  const { span, order, offset, className } = options;
  let style = applyVarGroup("span", span, options.style);
  style = applyVarGroup("order", order, style);
  style = applyVarGroup("offset", offset, style);

  let phoneSpan: CellIndex | undefined;
  let phoneOrder: CellIndex | undefined;
  let phoneOffset: CellIndex | undefined;
  let tabletSpan: CellIndex | undefined;
  let tabletOrder: CellIndex | undefined;
  let tabletOffset: CellIndex | undefined;
  let desktopSpan: CellIndex | undefined;
  let desktopOrder: CellIndex | undefined;
  let desktopOffset: CellIndex | undefined;
  if (span && typeof span === "object") {
    ({ phone: phoneSpan, tablet: tabletSpan, desktop: desktopSpan } = span);
  }
  if (order && typeof order === "object") {
    ({ phone: phoneOrder, tablet: tabletOrder, desktop: desktopOrder } = order);
  }
  if (offset && typeof offset === "object") {
    ({
      phone: phoneOffset,
      tablet: tabletOffset,
      desktop: desktopOffset,
    } = offset);
  }

  return {
    style,
    className: cnb(
      !!span && styles.span,
      !!order && styles.order,
      !!offset && styles.offset,
      typeof phoneSpan === "number" && styles.phoneSpan,
      typeof phoneOrder === "number" && styles.phoneOrder,
      typeof phoneOffset === "number" && styles.phoneOffset,
      typeof tabletSpan === "number" && styles.tabletSpan,
      typeof tabletOrder === "number" && styles.tabletOrder,
      typeof tabletOffset === "number" && styles.tabletOffset,
      typeof desktopSpan === "number" && styles.desktopSpan,
      typeof desktopOrder === "number" && styles.desktopOrder,
      typeof desktopOffset === "number" && styles.desktopOffset,
      className,
    ),
  };
}

import { Box, type BoxProps } from "@react-md/core/box/Box";
import { Card } from "@react-md/core/card/Card";
import { cnb } from "cnbuilder";
import { type CSSProperties, type ReactElement } from "react";

import styles from "./MaterialGridCustomizationExample.module.scss";

export default function MaterialGridCustomizationExample(): ReactElement {
  return (
    <MaterialGrid>
      <Card {...gridCell({ order: 2, className: styles.container })}>
        Cell 1
      </Card>
      <Card className={styles.container}>Cell 2</Card>
      <Card
        {...gridCell({
          span: { phone: 4, tablet: 3, desktop: 6 },
          className: styles.container,
        })}
      >
        Cell 3
      </Card>
      <Card
        {...gridCell({ offset: { tablet: 4 }, className: styles.container })}
      >
        Cell 4
      </Card>
      <Card className={styles.container}>Cell 5</Card>
    </MaterialGrid>
  );
}

function MaterialGrid(
  props: Omit<BoxProps, "grid" | "gridColumns">,
): ReactElement {
  return (
    <Box {...props} grid gridColumns={{ phone: 4, tablet: 8, desktop: 12 }} />
  );
}

type Breakpoint = "phone" | "tablet" | "desktop";
type CellIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
type Breakpoints = { [key in Breakpoint]?: CellIndex };
type ValueOrBreakpoints = CellIndex | Breakpoints;

declare module "react" {
  type CellProperty = "span" | "order" | "offset";
  type CellPropertyWithBreakpoint =
    | CellProperty
    | `${Breakpoint}-${CellProperty}`;

  type CellProperties = {
    [name in `--cell-${CellPropertyWithBreakpoint}`]?: string | number;
  };

  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
  interface CSSProperties extends CellProperties {}
}

const applyVar = (
  type: "span" | "order" | "offset",
  breakpoint: Breakpoint | "",
  value?: ValueOrBreakpoints,
  style?: CSSProperties,
): CSSProperties | undefined => {
  if (typeof value !== "string" && typeof value !== "number") {
    return style;
  }

  const name = breakpoint
    ? (`--cell-${breakpoint}-${type}` as const)
    : (`--cell-${type}` as const);
  return {
    ...style,
    [name]: value,
  };
};

const BREAKPOINTS = ["phone", "tablet", "desktop"] as const;

const applyVarGroup = (
  type: "span" | "order" | "offset",
  value?: ValueOrBreakpoints,
  style?: CSSProperties,
): CSSProperties | undefined => {
  let combinedStyle = applyVar(type, "", value, style);
  if (value && typeof value === "object") {
    for (const breakpoint of BREAKPOINTS) {
      combinedStyle = applyVar(
        type,
        breakpoint,
        value[breakpoint],
        combinedStyle,
      );
    }
  }
  return combinedStyle;
};

interface GridCellStyles {
  style?: CSSProperties;
  className?: string;
}

interface GridCellOptions extends GridCellStyles {
  span?: ValueOrBreakpoints;
  order?: ValueOrBreakpoints;
  offset?: ValueOrBreakpoints;
}

function gridCell(options: GridCellOptions): GridCellStyles {
  const { span, order, offset, className } = options;
  let style = applyVarGroup("span", span, options.style);
  style = applyVarGroup("order", order, style);
  style = applyVarGroup("offset", offset, style);

  let phoneSpan: CellIndex | undefined;
  let phoneOrder: CellIndex | undefined;
  let phoneOffset: CellIndex | undefined;
  let tabletSpan: CellIndex | undefined;
  let tabletOrder: CellIndex | undefined;
  let tabletOffset: CellIndex | undefined;
  let desktopSpan: CellIndex | undefined;
  let desktopOrder: CellIndex | undefined;
  let desktopOffset: CellIndex | undefined;
  if (span && typeof span === "object") {
    ({ phone: phoneSpan, tablet: tabletSpan, desktop: desktopSpan } = span);
  }
  if (order && typeof order === "object") {
    ({ phone: phoneOrder, tablet: tabletOrder, desktop: desktopOrder } = order);
  }
  if (offset && typeof offset === "object") {
    ({
      phone: phoneOffset,
      tablet: tabletOffset,
      desktop: desktopOffset,
    } = offset);
  }

  return {
    style,
    className: cnb(
      !!span && styles.span,
      !!order && styles.order,
      !!offset && styles.offset,
      typeof phoneSpan === "number" && styles.phoneSpan,
      typeof phoneOrder === "number" && styles.phoneOrder,
      typeof phoneOffset === "number" && styles.phoneOffset,
      typeof tabletSpan === "number" && styles.tabletSpan,
      typeof tabletOrder === "number" && styles.tabletOrder,
      typeof tabletOffset === "number" && styles.tabletOffset,
      typeof desktopSpan === "number" && styles.desktopSpan,
      typeof desktopOrder === "number" && styles.desktopOrder,
      typeof desktopOffset === "number" && styles.desktopOffset,
      className,
    ),
  };
}

@use "everything" as *;

.span {
  grid-column: span var(--cell-span, 1);
}

.order {
  order: var(--cell-order);
}

.offset {
  grid-column-start: var(--cell-offset);
}

$breakpoints: (phone, tablet, desktop);

@each $breakpoint in $breakpoints {
  @include media($breakpoint) {
    .#{$breakpoint}Span {
      --cell-span: var(--cell-#{$breakpoint}-span);
    }
    .#{$breakpoint}Order {
      --cell-span: var(--cell-#{$breakpoint}-order);
    }
    .#{$breakpoint}Offset {
      --cell-span: var(--cell-#{$breakpoint}-order);
    }
  }
}

// just for this demo
.container {
  min-height: 3rem;
}

@use "everything" as *;

.span {
  grid-column: span var(--cell-span, 1);
}

.order {
  order: var(--cell-order);
}

.offset {
  grid-column-start: var(--cell-offset);
}

$breakpoints: (phone, tablet, desktop);

@each $breakpoint in $breakpoints {
  @include media($breakpoint) {
    .#{$breakpoint}Span {
      --cell-span: var(--cell-#{$breakpoint}-span);
    }
    .#{$breakpoint}Order {
      --cell-span: var(--cell-#{$breakpoint}-order);
    }
    .#{$breakpoint}Offset {
      --cell-span: var(--cell-#{$breakpoint}-order);
    }
  }
}

// just for this demo
.container {
  min-height: 3rem;
}

Box Class Name Function

The box styles can also be applied using the box class name function. It supports all the box styling options and can be applied to any element that supports display: flex or display: grid.

Setting the gridColumns to a number with the box class name function does not enforce the provided number of columns like the Box component. It will only update the --rmd-box-item-min-size to 0. Use the boxStyles utility if the number of columns must be enforced.

import { box } from "@react-md/core/box/styles";
import { Fieldset } from "@react-md/core/form/Fieldset";
import { Form } from "@react-md/core/form/Form";
import { Legend } from "@react-md/core/form/Legend";
import { TextField } from "@react-md/core/form/TextField";
import { type ReactElement } from "react";

export default function BoxClassNameFunctionExample(): ReactElement {
  return (
    <Form>
      <Fieldset className={box({ grid: true, gridColumns: 3 })}>
        <Legend style={{ marginBottom: "1em" }}>Name</Legend>
        <TextField label="First Name" autoCompleteValue="given-name" required />
        <TextField label="Middle Name" autoCompleteValue="additional-name" />
        <TextField label="Last Name" autoCompleteValue="family-name" required />
      </Fieldset>
    </Form>
  );
}

import { box } from "@react-md/core/box/styles";
import { Fieldset } from "@react-md/core/form/Fieldset";
import { Form } from "@react-md/core/form/Form";
import { Legend } from "@react-md/core/form/Legend";
import { TextField } from "@react-md/core/form/TextField";
import { type ReactElement } from "react";

export default function BoxClassNameFunctionExample(): ReactElement {
  return (
    <Form>
      <Fieldset className={box({ grid: true, gridColumns: 3 })}>
        <Legend style={{ marginBottom: "1em" }}>Name</Legend>
        <TextField label="First Name" autoCompleteValue="given-name" required />
        <TextField label="Middle Name" autoCompleteValue="additional-name" />
        <TextField label="Last Name" autoCompleteValue="family-name" required />
      </Fieldset>
    </Form>
  );
}

Box Styles Utility Function

If the number of columns or item size need to be controlled, use the boxStyles utility function instead. It returns a style object with CSS variables and the corresponding class names.

import { boxStyles } from "@react-md/core/box/styles";
import { Fieldset } from "@react-md/core/form/Fieldset";
import { Form } from "@react-md/core/form/Form";
import { Legend } from "@react-md/core/form/Legend";
import { TextField } from "@react-md/core/form/TextField";
import { type ReactElement } from "react";

export default function BoxStylesUtilityFunctionExample(): ReactElement {
  return (
    <Form>
      <Fieldset
        {...boxStyles({
          grid: true,
          gridColumns: { phone: 1, desktop: 3 },
          gridItemSize: { tablet: "12rem" },
        })}
      >
        <Legend style={{ marginBottom: "1em" }}>Name</Legend>
        <TextField label="First Name" autoCompleteValue="given-name" required />
        <TextField label="Middle Name" autoCompleteValue="additional-name" />
        <TextField label="Last Name" autoCompleteValue="family-name" required />
      </Fieldset>
    </Form>
  );
}

import { boxStyles } from "@react-md/core/box/styles";
import { Fieldset } from "@react-md/core/form/Fieldset";
import { Form } from "@react-md/core/form/Form";
import { Legend } from "@react-md/core/form/Legend";
import { TextField } from "@react-md/core/form/TextField";
import { type ReactElement } from "react";

export default function BoxStylesUtilityFunctionExample(): ReactElement {
  return (
    <Form>
      <Fieldset
        {...boxStyles({
          grid: true,
          gridColumns: { phone: 1, desktop: 3 },
          gridItemSize: { tablet: "12rem" },
        })}
      >
        <Legend style={{ marginBottom: "1em" }}>Name</Legend>
        <TextField label="First Name" autoCompleteValue="given-name" required />
        <TextField label="Middle Name" autoCompleteValue="additional-name" />
        <TextField label="Last Name" autoCompleteValue="family-name" required />
      </Fieldset>
    </Form>
  );
}