jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-27 19:26:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation and blog post for get grid size

Browse Source
This commit is contained in:
Paul Bottein 2024-03-06 15:31:03 +01:00
parent 69c704b493
commit 7a5e856813
No known key found for this signature in database
2 changed files with 42 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
blog/2024-03-06-getGridSize.md Normal file
View File

@ -0,0 +1,30 @@
---
author: Paul Bottein
authorURL: https://github.com/piitaya
authorTwitter: piitaya
title: "Grid section support for custom cards"
---
The `2024.3` Home Assistant introduced a new type of view: the [section view](https://rc.home-assistant.io/dashboards/sections/).
To support this new view, your card must provide a `getGridSize` method. Otherwise, your card will be full width on the grid. The section grid is composed of 4 columns and as many row as needed.
If you want your custom card to take 2 columns and 1 row (the same as tile card), you must define the follow code.
```js
class MyCustomCard {
/*
...all your existing custom card code
*/
// This will tell the grid section that
// your card will take 2 columns and 1 row.
public getGridSize() {
return [2, 1];
}
}
```
This method must returns the space your card on the grid section as a array containing the number of columns and rows. It is recommended that the size doesn't rely on state or other dynamic state attributes to avoid any layout change when the state change. Try to rely only on some fixed state attributes (e.g. `supported features`) and the card configuration to have a predictable size.
For more information about this new grid system, see [the blog post](https://home-assistant.io/blog/2024/03/04/dashboard-chapter-1/).

13
docs/frontend/custom-ui/custom-card.md
View File

@ -50,6 +50,12 @@ class ContentCardExample extends HTMLElement {
getCardSize() {
return 3;
}
// Size of your card on the grid. Home Assistant uses this to organize
// cards on the section grid.
getGridSize() {
return [2, 3];
}
}
customElements.define("content-card-example", ContentCardExample);
@ -90,6 +96,10 @@ return customElements
.then(() => element.getCardSize());
```
Your card can define a `getGridSize` method to support [section view](https://home-assistant.io/dashboards/sections/), This method must returns the space your card on the grid section as a array containing the number of columns and rows.
The section grid is composed of 4 columns and as many row as needed. If the method returns `[2, 3]`, your card will take 2 columns and 3 rows on the grid. If this method is not defined, your card will be full width and the height of your card will be set to `auto`.
It's recommended that the size doesn't rely on state or other dynamic state attributes to avoid any layout change when the state change. Try to rely only on some fixed state attributes (e.g. `supported features`) and the card configuration to have a predictable size.
Your card can define a `getConfigElement` method that returns a custom element for editing the user configuration. Home Assistant will display this element in the card editor in the dashboard.
## Advanced example
@ -267,7 +277,8 @@ window.customCards.push({
name: "Content Card",
preview: false, // Optional - defaults to false
description: "A custom card made by me!", // Optional
documentationURL: "https://developers.home-assistant.io/docs/frontend/custom-ui/custom-card/", // Adds a help link in the frontend card editor
documentationURL:
"https://developers.home-assistant.io/docs/frontend/custom-ui/custom-card/", // Adds a help link in the frontend card editor
});
```