> Markdown version of [CSS Grid Layouts](https://vaadin.com/docs/next/building-apps/ui-basics/layouts/css-grid). Section index: [llms.txt](https://vaadin.com/docs/next/building-apps/llms.txt)

# CSS Grid Layouts

CSS Grid is a *two-dimensional* layout system: it arranges children into rows **and** columns at the same time. Use it when the one-dimensional layouts — `HorizontalLayout` and `VerticalLayout`, which arrange a single row or column — aren’t enough, such as for card grids or fixed page grids. For those one-dimensional layouts, see the [Arrange with Layouts](https://vaadin.com/docs/next/building-apps/ui-basics/layouts.md) overview.

CSS Grid is plain CSS, so it works with any theme. Vaadin has no dedicated grid layout component; instead you apply grid styling to an ordinary container.

> **Important: CSS Grid is not the Vaadin Grid component**
>
> This article is about *CSS Grid*, the browser layout system. It is unrelated to the Vaadin [Grid](https://vaadin.com/docs/next/components/grid.md) component, which is a data table for displaying rows of items.

## <a id="when-to-use-css-grid"></a>When to Use CSS Grid

| Need                                         | Use                                                                                                  |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| A single row or column of components         | [HorizontalLayout / VerticalLayout](https://vaadin.com/docs/next/building-apps/ui-basics/layouts.md) |
| Form fields with labels                      | [Form Layout](https://vaadin.com/docs/next/components/form-layout.md)                                |
| User-rearrangeable dashboard widgets         | [Dashboard](https://vaadin.com/docs/next/components/dashboard.md)                                    |
| A fixed two-dimensional grid, or a card grid | CSS Grid (this article)                                                                              |

## <a id="applying-css-grid"></a>Applying CSS Grid

Because there’s no grid layout component, add `display: grid` to a container through a CSS class, then add the components as its children — each child becomes a cell:

```java
Div productGrid = new Div();
productGrid.addClassName("product-grid");
productGrid.add(card1, card2, card3, card4, card5, card6);
```

```css
.product-grid {
    display: grid;
    grid-template-columns: repeat(3, 1fr); /* three equal-width columns */
    gap: 1rem;                             /* space between cells */
}
```

`1fr` is a *fraction* of the available space, so `repeat(3, 1fr)` makes three columns that share the width equally. Rows are created automatically as items fill the columns. Use `gap` for spacing between cells rather than margins on the children.

For how to attach a stylesheet and apply class names from Java, see [Add Styling](https://vaadin.com/docs/next/building-apps/ui-basics/add-styling.md).

## <a id="fluid-grids-that-wrap-automatically"></a>Fluid Grids That Wrap Automatically

For a card grid that should fit as many columns as the screen allows, combine `repeat()` with `auto-fill` and `minmax()`. This adapts to the available width **without any media queries**:

```css
.card-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
    gap: 1rem;
}
```

Each column is at least `220px` wide and grows to fill leftover space; the browser packs in as many columns as fit and wraps the rest to new rows. For most card grids this is simpler and smoother than defining breakpoints by hand. When you do need breakpoint-based changes, see [Responsive Layouts](https://vaadin.com/docs/next/building-apps/ui-basics/layouts/responsive.md).

## <a id="spanning-multiple-cells"></a>Spanning Multiple Cells

A child can span several columns or rows. Add a class to the component and set `grid-column` or `grid-row`:

```java
featuredCard.addClassName("featured");
```

```css
.featured {
    grid-column: span 2; /* take up two columns */
}
```

## <a id="lumo-utility-classes"></a>Lumo Utility Classes

> **Note:** Utility classes require the **Lumo theme**. With the Aura theme, write the CSS shown above.

If you use Lumo, you can build a grid without a separate stylesheet by applying utility classes from Java — `LumoUtility.Display.GRID` together with the grid-column and `LumoUtility.Gap` utilities:

```java
productGrid.addClassNames(
        LumoUtility.Display.GRID,
        LumoUtility.Gap.MEDIUM);
```

For the full list of grid and gap utility classes, see the [Lumo Utility Classes](https://vaadin.com/docs/next/styling/themes/lumo/utility-classes.md) reference.

## <a id="best-practices"></a>Best Practices

1. **Use CSS Grid for two-dimensional layouts only.** For a single row or column, `HorizontalLayout` or `VerticalLayout` is simpler — see [Arrange with Layouts](https://vaadin.com/docs/next/building-apps/ui-basics/layouts.md).

2. **Prefer `auto-fill` with `minmax()` for card grids.** It wraps fluidly without media queries; reach for breakpoints only when the layout must change in a way `minmax()` can’t express.

3. **Use `gap` for spacing,** not margins on the children.

4. **Don’t confuse CSS Grid with the Vaadin `Grid` component** — one is a layout system, the other a data table.