# Styling
{% hint style="info" %}
Styling for widgets is not the same as for custom views. While there are some variables and classes with the same name, the actual styling might differ.
{% endhint %}
The provided CSS variables and classes are prefixed with homey, so `--homey` for variables and `.homey` for classes. We recommend using these CSS variables and classes as much as possible. Most widgets can be created using only these classes or by adding just a few lines of custom CSS. However, feel free to use them as a starting point and add custom styling to your liking.
## Widget
Your widget consists of a title, a frame, and the content you provide. While you have limited control over the title and frame, most of this style guide focuses on styling the content within your widget.
### Title
The default title of your widget is the name set in `widget.compose.json` (see [#widget.compose.json](https://apps.developer.homey.app/the-basics/widgets/..#widget.compose.json "mention")). When users add your widget to their dashboard, they can choose to either change the title or hide it entirely.
Empty widget with title (left) and without title (right).
### Frame
Your widget’s content is placed inside a frame with rounded corners and a shadow. While you can't change the border radius, shadow or width of the frame, you do have control over the height (see [#widget.compose.json](https://apps.developer.homey.app/the-basics/widgets/..#widget.compose.json "mention")) and the background color.
Additionally, you can set the `transparent` property in [`widget.compose.json`](https://apps.developer.homey.app/the-basics/widgets/..#widget.compose.json), which allows for a fully transparent background. This option is ideal for creating seamless widgets that integrate smoothly without the default background color.
#### Background color
By default, the background color of your widget is set to `--homey-background-color`. This semantic color variable (see [#semantic](#semantic "mention")) can also be used for other elements in your widget.
CSS Variable
Value
--homey-background-color
--homey-color-mono-000 (white) in light mode and --color-mono-050 (dark grey) in dark mode (see #palette).
You can apply a different background color to the body of your widget:
```html
```
```css
.my-custom-body {
background-color: var(--homey-color-blue);
}
```
## Spacing
When widgets are next to each other, it's visually pleasing to have the elements inside of the widgets aligned. In addition, the distances between elements inside of a widget make a huge difference in how organised, or cluttered, the dashboard feels.
### Space Units
To maintain consistent spacing across your widgets, we provide a set of predefined CSS variables based on a space unit, `--homey-su`. This unit serves as the foundation for all spacing-related styles. You can use these variables to apply consistent margins, padding, and other spacing properties to your widget elements.
We don't use space units for sizing properties, like width and height. The size of an element is often determined by other factors, like text length, or by the available space left after applying margins and paddings (e.g. `width: 100%;`).
The base space unit is set to 4px. Each derived variable is a multiple of the base space unit.
```css
--homey-su: 4px; /* base */
--homey-su-1: calc(var(--homey-su) * 1); /* 4px */
--homey-su-2: calc(var(--homey-su) * 2); /* 8px */
--homey-su-3: calc(var(--homey-su) * 3); /* 12px */
--homey-su-4: calc(var(--homey-su) * 4); /* 16px */
--homey-su-5: calc(var(--homey-su) * 5); /* 20px */
--homey-su-6: calc(var(--homey-su) * 6); /* 24px */
--homey-su-7: calc(var(--homey-su) * 7); /* 28px */
--homey-su-8: calc(var(--homey-su) * 8); /* 32px */
```
#### Usage Example
You can use these variables to ensure consistent spacing within your widgets. For example:
```css
.widget-item {
margin-left: var(--homey-su-2);
padding: var(--homey-su-4)
}
```
### Widget Padding
To align the elements on the edges of your the widget to other widgets, we offer the following classes:
CSS Class
Purpose
.homey-widget
Default and recommended for most widgets. This class applies a padding of --homey-su-4.
.homey-widget-small
Used to save space in small widgets, this class applies a padding of --homey-su-2.
.homey-widget-full
Use this class, or omit the class entirely, for widgets where you need the full space (e.g. tables or images). The default padding for the element is 0.
#### Usage Examples
The space between your widget’s content and the edge of its frame affects how well it aligns with other widgets. To ensure a consistent look across the dashboard, we’ve added the `.homey-widget` class to the body of your widget by default. This class applies a padding of `--homey-su-4` (16px, see [#space-units](#space-units "mention")) to your widget:
```html
```
For smaller widgets, this padding might take up more space than desired. In such cases, you can use the `.homey-widget-small` class, which sets the padding to `--homey-su-2` (8px):
```html
```
For widgets that include elements like tables or images that need to extend to the edges of the frame, you can either remove the `.homey-widget` class or use the `.homey-widget-full` class, which sets the padding to 0. Alternatively, you can move the `.homey-widget` class to a child element for the rest of your content:
<body class="homey-widget-full">
<!-- Full size element here. -->
<div class="homey-widget">
<!-- Content of you widget here. -->
</div>
</body>
## Text
Describing every possible combination of text properties would be too extensive. Instead, we offer several text presets as CSS classes that cover a wide range of use cases, along with CSS variables for font size, font weight, line height and color. Additionally, we provide classes for text alignment.
### Text Presets
The following CSS classes are a great starting point for styling your widget. They apply a font size smaller than the widget title, and their combination of font weight, line height, and color helps establish a clear visual hierarchy within your widget.
CSS Class
Purpose
.homey-text-bold
Used for titles or a singular important text.
.homey-text-medium
Used to make text stand out, for strong text or subtitles.
.homey-text-regular
Default for most text.
.homey-text-small
Used for small text on it's own.
.homey-text-small-light
Used for small text next to other texts.
In the image below are examples of when to use these classes.
Example usage of CSS classes for text in timeline widget (left) and lights widget (right).
#### Usage Example
<h1 class="homey-text-bold">Hello World!</h1>
<p class="homey-text-regular">How are you?</p>
### Variables
We provide CSS variables for font size, font weight, line height, and color. To maintain consistency, all text on the dashboard follows specific combinations of font sizes and font weights. When using the provided CSS variables, refer to the table below for the recommended combinations. Additionally, ensure that the line height you choose matches the corresponding font size (see [#line-height](#line-height "mention")).
#### Table of combinations for font size and font weight
regular
medium
bold
xxlarge
false
false
true
xlarge
false
false
true
large
false
true
false
default
true
true
true
small
true
false
false
The image below shows several combinations used in widgets.
Example usage of CSS variables for text in weather widget (left) and battery widget (right).
#### Font Size
It is recommended to use text sizes smaller than the title above the widgets, which is 20px. The default text size `--homey-font-size-default` is 17px.
We provide the following variables:
CSS Variable
Value
Purpose
--homey-font-size-xxlarge
32px
Used for numbers only.
--homey-font-size-xlarge
24px
Use sparingly, only for short phrases or single words that really have to stand out.
--homey-font-size-large
20px
Used for numbers only.
--homey-font-size-default
17px
Default for most text.
--homey-font-size-small
14px
For captions, tables, underneath other text, or inside specific elements.
#### Line Height
We have a specific line height for every font size. It is highly recommended to always use these together.
CSS Variable
Value
Use with font size
--homey-line-height-xxlarge
40px
--homey-font-size-xxlarge
--homey-line-height-xlarge
32px
--homey-font-size-xlarge
--homey-line-height-large
28px
--homey-font-size-large
--homey-line-height-default
24px
--homey-font-size-default
--homey-line-height-small
20px
--homey-font-size-small
#### Font Weight
Important text, such as titles, can be made to stand out by adjusting the font weight. Refer to the table above (see [#table-of-combinations-for-font-size-and-font-weight](#table-of-combinations-for-font-size-and-font-weight "mention")) to find the appropriate font weight for your chosen font size.
CSS Variable
Value
Purpose
--homey-font-weight-bold
700
Used for titles.
--homey-font-weight-medium
500
Used to make text stand out, for strong text or subtitles.
--homey-font-weight-regular
400
Default for most text.
#### Text Color
The default text color is `--homey-text-color`. This color depends on if the widget is shown in light or dark mode (see [#light-and-dark-mode](#light-and-dark-mode "mention")) and fits nicely on a background with `--homey-background-color` (see [#background-color](#background-color "mention")).
For use on different backgrounds or different purposes, we offer the following semantic color variables (see [#semantic](#semantic "mention")).
| CSS Variable | Purpose |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| `--homey-text-color` | Default text color. |
| `--homey-text-color-light` | Used for text that's less important, or disabled. |
| `--homey-text-color-white` | White text, independent of light or dark mode. Used for text on dark or colored backgrounds. |
| `--homey-text-color-blue` | Blue text. |
| `--homey-text-color-green` | Green text. |
| `--homey-text-color-orange` | Orange text. |
| `--homey-text-color-red` | Red text. |
| `--homey-text-color-highlight` | Text to highlight something. |
| `--homey-text-color-success` | Text for success case. |
| `--homey-text-color-warning` | Text for warnings. |
| `--homey-text-color-danger` | Text for errors. |
#### Usage Example
```html
HELP ME!
```
```css
.my-custom-text {
font-size: var(--homey-font-size-medium);
font-weight: var(--homey-font-weight-bold);
line-height: var(--homey-line-height-medium); /* Matches with font-size. */
color: var(--homey-text-color-danger);
}
```
### Text Alignment
We have the following CSS classes to change the text alignment to left, center or right.
CSS Class
Purpose
.homey-text-align-left
Align text left.
.homey-text-align-center
Align text center.
.homey-text-align-right
Align text right.
## Colors
We provide a color palette that includes grayscale, blues, greens, orange, and reds, in addition to semantic colors for specific purposes. Our palette supports both light and dark mode, with each CSS variable automatically adjusting to the active mode. However, the actual color may differ between modes.
### Light & Dark Mode
The dashboard switches between light and dark mode based on the user’s settings. By default, the widget background is white in light mode and dark grey in dark mode.
If you want your widget to always appear in dark mode, regardless of the user's settings, you can add the `.homey-dark-mode` class to the element. This forces the widget to stay in dark mode.
CSS Class
Purpose
.homey-dark-mode
Force widget to dark mode independent of user settings.
#### Usage Example
```html
```
If you want to check if darkmode is enabled you can use the selector `.homey-dark-mode my-selector`.
### Palette
Our color palette includes grayscale, blues, greens, orange, and reds. While you can use these CSS variables directly, we recommend using the semantic color variables where possible (see [#semantic](#semantic "mention")).
The grayscale is prefixed with `--homey-color-mono` and ranges from `--homey-color-mono-000`(white in light mode) to `--homey-color-mono-1000` (black in light mode).
Color palette grayscale in light mode (left) and dark mode (right).
The blue, green, orange and red colors are prefixed as `--homey-color-blue`, `--homey-color-green`, `--homey-color-orange` and `--homey-color-red` respectively. These colors range from `050` to `900`, except for orange, which only has the `500` value available. These colors remain the same in both light and dark mode.
Color palette for blue (top-left), green (bottom-left), orange (top-right) and red (bottom-right).
### Semantic
To help you select the right color from our palette, we provide CSS variables for specific purposes, known as semantic color variables. These variables are defined using the palette CSS variables above ( see [#palette](#palette "mention")). So no new colors are introduced—just clarification on their intended use cases. This ensures consistent color usage across your widgets while keeping the palette simple and easy to apply.
CSS Variable
Purpose
--homey-color-white
White color independent of light or dark mode.
--homey-color-blue
General purpose blue color.
--homey-color-green
General purpose green color.
--homey-color-orange
General purpose orange color.
--homey-color-red
General purpose red color.
--homey-color-highlight
Highlight.
--homey-color-success
Success.
--homey-color-warning
Warning.
--homey-color-danger
Danger.
The semantic CSS variables for [#background-color](#background-color "mention"), [#text-color](#text-color "mention"), [#lines-and-borders](#lines-and-borders "mention") and [#icons](#icons "mention") can be found in their respective sections.
## Lines & Borders
Because the widget’s frame already has a shadow, we recommend avoiding additional shadows on elements inside your widget, as shadows within shadows can quickly become cluttered. Instead, we offer several CSS variables and classes to help you apply clean and consistent lines and borders to your elements.
### Borders
CSS Class
Purpose
.homey-border
Adds a border to all sides of the element.
.homey-border-top
Add a border to the top of the element.
.homey-border-right
Add a border to the right side of the element.
.homey-border-bottom
Add a border to the bottom of the element.
.homey-border-left
Add a border to the left side of the element.
### Lines
The CSS classes for borders use the following CSS variables. These CSS variables can also be applied to other lines within your widget.
We provide two semantic color variables for line colors (see [#semantic](#semantic "mention")):
CSS Variable
Purpose
--homey-line-color
Used for most lines. The default line color.
--homey-line-color-light
Used for light lines that should stand out less.
In almost all cases, we use a 1px solid line with the line colors mentioned above. You can use the following CSS variables to apply consistent lines like these to your widget elements:
CSS Variable
Purpose
--homey-line
Used for most lines.
--homey-line-light
Used for light lines that should stand out less.
### Border Radius
We offer the following CSS variables for applying a border radius to your elements:
CSS Variable
Purpose
--homey-border-radius-small
Only use where the default border radius is too big.
--homey-border-radius-default
Default border radius.
#### Usage Example
```html
```
```css
.my-custom-item {
border: var(--homey-line-light);
border-radius: var(--homey-border-radius-default);
}
```
## Icons
For our icons, we always use SVGs and recommend you do the same for your custom icons, as SVGs ensure sharp display at any size. You can place your custom icons, along with other assets, in your public folder (see [#index.html](https://apps.developer.homey.app/the-basics/widgets/..#index.html "mention")).
### Custom Icons
If you want to add a custom icon, you can extend the .homey-custom-icon- class. Simply add a class starting with `.homey-custom-icon-` (e.g., `.homey-custom-icon-example`) to your element. In your CSS, use your SVG as the `mask-image` and include `-webkit-mask-image` for older browser support.
#### Usage Example
```html
```
```css
.homey-custom-icon-example {
-webkit-mask-image: url('example.svg'); /* Browser support. */
mask-image: url('example.svg');
}
```
### Variables
We have the following semantic color variables for icon colors (see [#semantic](#semantic "mention")):
CSS Variable
Purpose
--homey-icon-color-dark
Default icon color.
--homey-icon-color-light
Used less important icons or disabled states.
--homey-icon-color-white
White icons, independent of light or dark mode.
--homey-icon-color-blue
Blue icons.
--homey-icon-color-green
Green icons.
--homey-icon-color-orange
Orange icons.
--homey-icon-color-red
Red icons.
We have the following CSS variable for icon sizing:
CSS Variable
Value
Purpose
--homey-icon-size-medium
20px
Default icon size.
--homey-icon-size-regular
16px
Used in line with regular text.
--homey-icon-size-small
14px
Used in line with small text.
#### Usage Example
```html
```
```css
.homey-custom-icon-example {
--homey-icon-color: var(--homey-icon-color-green);
--homey-icon-size: var(--homey-icon-size-small);
-webkit-mask-image: url('example.svg');
mask-image: url('example.svg');
}
```
## Tables
We offer two different table styles: tables with lines between cells, using the `.homey-table` class, and tables with striped rows, using the `.homey-table-striped` class. We recommend using the `.homey-table-striped` class only for tables with a few columns or when the content has enough horizontal spacing that dividing lines aren’t necessary.
CSS Class
Purpose
.homey-table
Default table styling.
.homey-table-striped
Used for tables with only a few columns.
Example of CSS classes .homey-table (left) and .homey-table-striped (right).
To change the text alignment in the cells of the table, you can apply the text alignment classes (see [#text-alignment](#text-alignment "mention")) to the table element.
#### Usage Example
```html
Header 1
Header 2
Header 3
Row 1, Cell 1
Row 1, Cell 2
Row 1, Cell 3
Row 2, Cell 1
Row 2, Cell 2
Row 2, Cell 3
Row 3, Cell 1
Row 3, Cell 2
Row 3, Cell 3
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://apps.developer.homey.app/the-basics/widgets/styling.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
