# layout-card: four Lovelace layouts, and a column count that ignores your grid

> layout-card is a Home Assistant custom card that replaces the Lovelace view layout with Masonry, Horizontal, Vertical or Grid, and it deliberately exposes fewer options than its 1.0 line did. The mechanics are column based, and a few of the option interactions are surprising.

**thomasloven/lovelace-layout-card** — 🔹 Get more control over the placement of lovelace cards.

- Repository: https://github.com/thomasloven/lovelace-layout-card
- Stars: 1,262 · Forks: 134
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/thomasloven-lovelace-layout-card

## Four view types, selected from the same dropdown as the built-in ones

layout-card adds four view layouts to Lovelace: Masonry, Horizontal, Vertical and Grid, exposed as `custom:masonry-layout`, `custom:horizontal-layout`, `custom:vertical-layout` and `custom:grid-layout`. They appear in the view type dropdown next to the built-in options, so switching a view to one of them is a dropdown choice rather than a configuration rewrite.

The documented path is short. Open one of your Lovelace views, select "Edit Dashboard", click the pencil symbol next to the view name to open the view properties, choose "Masonry (layout-card)" from the "View type" dropdown, and save. The README notes with some relief that you should see no difference at all at this point, since the defaults reproduce the standard look.

The change becomes visible once you set the layout options:

```yaml
width: 300
max_cols: 10
```

With those values you get more, narrower columns of cards. The same thing can be written directly in the Lovelace configuration, where the view carries a `type` and an optional `layout` block:

```yaml
views:
  - title: Home
    type: custom:masonry-layout
    layout:
      width: 300
      max_cols: 10
    cards: ...
```

The card is distributed through HACS, and the repository carries a `hacs.json` and a badge marking it as a default HACS repository entry. Installation instructions point to a guide in the author's separate `hass-config` wiki rather than describing the steps here.

## The column algorithm is simple enough to predict

The first three layouts, Masonry, Horizontal and Vertical, are column based and work in a similar way, and the README describes the sequence in four steps.

First, a number of evenly sized columns is prepared based on the available space, the `width` option and the `max_cols` option. Second, the cards are placed into the columns one at a time in a method that depends on the current layout, which is what separates the three variants from one another. Third, any empty columns are removed. Fourth, the remaining columns are placed centered on screen.

That last pair of steps is why the layouts look tidy with few cards: a column that received nothing disappears, and what is left is centered rather than stretched to the edge. It also means the visible column count can be lower than `max_cols` at any moment, so a setting of ten is a ceiling rather than a promise.

The Grid layout is the odd one out and is not described by these four steps. The README points to it as the fallback when a layout behaves strangely, which implies it is built on a different arrangement, but the visible documentation does not spell out its placement rules or its own option set.

## The option table, and the defaults that quietly depend on the sidebar

The column based layouts accept a documented set of options, and reading the table closely is worthwhile because several defaults are conditional.

`width` is the size in pixels of each column and defaults to 300. `max_width` caps the width of a card, defaulting to one and a half times `width` when that is specified, and otherwise 500. `max_cols` is the maximum number of columns, defaulting to 4 if the sidebar is hidden and 3 if the sidebar is shown, so the same dashboard shows a different number of columns depending on where you are looking at it from. `rtl` places columns in right-to-left order and is off by default.

`column_widths` takes a `grid-template-columns` specification, `margin` and `padding` apply CSS to the layout itself, `height` sets a CSS height with `auto` by default, and `card_margin` sets the margin on each card, defaulting to `var(--masonry-view-card-margin, 4px 4px 8px)` so the card spacing follows the active Home Assistant theme.

The option with the most consequence is `reflow`. When it is `true`, the layout is reorganised when cards are hidden, which is what you want with conditional or entity-filter cards, and the README warns in the same cell that it may cause performance issues. It is off by default, which is a sensible default for a browser front end that has to stay responsive on a wall-mounted tablet.

## column_widths does not control how many columns you get

One note deserves to be lifted out of the option table, because it is the sort of thing that costs an evening. Even if `column_widths` is specified, the number of columns displayed depends only on the available space, the `width` option and the `max_cols` option. The README adds that if you get weird results, you should consider the Grid Layout.

In other words, `column_widths` shapes the columns that get created, but it does not create more of them. If you want ten narrow columns, `max_cols` has to allow ten and the viewport has to have room for ten. This is a design decision rather than an oversight: the column count is computed from a layout pass, and letting a CSS grid specification override the count would make the two systems fight over the same decision.

The consequence is that a dashboard authored on a wide monitor and viewed on a phone will not simply reflow into a different number of columns unless `max_cols` and `width` allow it. The `reflow` option addresses a different problem, namely cards disappearing, not the viewport getting narrower.

## layout-card nests a layout inside a card, and inherits a width ceiling

Beyond views, any layout can be used inside a Lovelace card through a card called `layout-card`:

```yaml
type: custom:layout-card
layout_type: custom:masonry-layout
layout:
  width: 300
  max_cols: 10
cards: ...
```

The card takes its `cards` and places them within itself according to the specified layout, and the `layout:` block accepts the same options as a view configuration.

The limitation is stated plainly in a note. `layout-card` is itself a card, so it cannot be wider than any other card in the same view, and every card you put inside it has to fit inside that same width. The author therefore describes it as of limited use except in panel mode, where the Lovelace view occupies the whole screen and a single card can be as wide as the viewport.

The note also warns about the default layout option, which the GUI editor shows for a layout-card. That default uses Lovelace's own default layout engine, which is basically the Horizontal layout without options, without the ability to hide cards, and with the column count based on the width of the window rather than of the layout-card. The author's recommendation is not to use it, but it is there.

Two different selection mechanisms therefore exist for the same thing: a dropdown in the view properties for views, and a `layout_type` key for cards inside a layout-card.

## Per-card column placement and the layout-break card

Individual cards can carry layout options of their own, attached through the `view_layout` parameter:

```yaml
type: entities
entities:
  - light.bed_light
view_layout:
  column: 2
```

This is how you place a specific card in a specific column, which the column based layouts otherwise would not let you do. The parameter is attached to the card rather than to the view, so the same card can be positioned differently in different views.

There is also a special card called `layout-break`:

```yaml
type: custom:layout-break
```

The README describes it as a special card that can be used to change how some layouts work, without going into detail about the mechanism. Its presence in a card list is a signal to the layout rather than something that renders, and a layout card is the natural place to experiment with it.

The repository layout backs the TypeScript side of this. The root holds `layout-card.js`, which is the bundled card, plus `src/` for the sources, `rollup.config.js` for the bundling, `tsconfig.json` for the TypeScript configuration, and a `test/` directory. The `package.json` shows the runtime dependency is `lit`, the web components library, and the build is a single Rollup command, `rollup -c`, with a watch mode alongside it. There is also a `.devcontainer/` directory for a containerised development environment.

## Fewer options, on purpose, and releases tied to Home Assistant versions

The second migration note in the README is about a deliberate reduction. Migrating from layout-card 1.0, which the author notes had a confusing version number of v16, to the current line means significantly fewer options than you may be used to. Two reasons are given.

The first is maintainability: as Home Assistant and Lovelace evolve, it becomes increasingly difficult to keep up with the more options you want to keep alive. The second is usability, with the stated aim of focusing on fewer options.

That is a rare and useful thing for a project to state outright, and it changes how you should read the option table. The table is short because a browser front end plugin that has to keep working against a fast moving host application is a maintenance liability, and the author has chosen to keep the surface small rather than to promise compatibility with everything that came before.

The release history shows the same pattern. The tags are v2.4.7 with the note "Fixes for Home Assistant 2025.10" from 2025-10-28, v2.4.6 with "Fixes for Home Assistant 2025.5" from 2025-05-13, and v2.4.5 with "Fix view editor with Home Assistant 2024.3" from 2024-02-29. The package version in `package.json` matches the tag, 2.4.7, so the card's version number and the Home Assistant release it targets are the same track. The last push was on 2026-05-09, and the project is licensed under MIT with the licence text in `LICENSE.txt`.

## Where layout-card is the wrong tool

The first wrong case is a dashboard that has to work on several Home Assistant versions without intervention. This is a front end plugin that manipulates the Lovelace view DOM, and the release history shows it breaking when the host changes. Running a card that has not been updated for your Home Assistant version is a gamble, and the symptom is a view that renders wrong or not at all.

The second is a need for a specific card to be wider than the rest of the view. That is precisely what `layout-card` cannot do, because it is a card inside a view, and the author says so. Panel mode is the documented exception, and if your dashboard is a normal view with a sidebar, that exception does not apply to you.

The third is a performance-sensitive dashboard. The `reflow` option, which reorganises the layout when cards are hidden, is documented as potentially causing performance issues, and it is the option you need if you use conditional or entity-filter cards. You can have the feature or the responsiveness, not necessarily both.

The fourth is an expectation of the 1.0 feature set. If your configuration uses options that were removed in the 2.x line, the card will ignore them, and the result is a layout that does not match what the configuration asks for. The fix is to read the current option table before migrating a dashboard, not to try the old keys and see what happens.

## Conclusion

Adopt layout-card if your Home Assistant dashboards are constrained by the default Lovelace grid and you want to control column width, column count and per-card column placement, especially in panel mode where a card can span the full width. Do not adopt it if you need the option set from the 1.0 line, because the author removed most of it for maintainability reasons, or if your dashboards rely on layouts that change in future Home Assistant releases, since the card is a front end plugin and each release here is a fix for a specific Home Assistant version. Before you install it, check which Home Assistant version you run against the release notes, and set the `width` and `max_cols` options first, because the default column count changes depending on whether the sidebar is visible.

## FAQ

### How do I add the layout-card Masonry view to a Home Assistant dashboard?

Open the view, select "Edit Dashboard", click the pencil next to the view name, choose "Masonry (layout-card)" from the View type dropdown and save. Then set the layout options, for example `width: 300` and `max_cols: 10`, in the Layout Options box.

### What is the difference between the Masonry, Horizontal, Vertical and Grid layouts?

The README says Masonry, Horizontal and Vertical are column based and work similarly: evenly sized columns are prepared from the available space, `width` and `max_cols`, cards are placed into them one at a time, empty columns are removed and the rest are centered. Grid is described separately, and the README recommends it when the column layouts give odd results.

### How do I set a card into a specific column in layout-card?

Attach the `view_layout` parameter to that card, for example `view_layout:` with `column: 2` underneath the card configuration. The option is attached to the card, so the same card can be placed differently in different views.

### Does layout-card work with Home Assistant panel mode?

Yes. The README notes that `layout-card` is itself a card and cannot be wider than the other cards in the same view, and that this limits its use except in panel mode, where a card can use the full width of the view.

## Sources

- [Issues](https://github.com/thomasloven/lovelace-layout-card/issues)
- [License: MIT](https://github.com/thomasloven/lovelace-layout-card/blob/master/LICENSE)
- [README](https://github.com/thomasloven/lovelace-layout-card/blob/master/README.md)
- [Releases](https://github.com/thomasloven/lovelace-layout-card/releases)
- [thomasloven/lovelace-layout-card on GitHub](https://github.com/thomasloven/lovelace-layout-card)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/thomasloven-lovelace-layout-card