Styling

Styling your widget with the provided CSS variables and classes helps it fit nicely alongside other widgets on the user’s dashboard.

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.

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.

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). When users add your widget to their dashboard, they can choose to either change the title or hide it entirely.

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) and the background color.

Additionally, you can set the transparent property in 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) can also be used for other elements in your widget.

CSS Variable Value

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).

--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:

<body class="homey-widget my-custom-body">
  <!-- Content of you widget here. -->
</body>

.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.

--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:

.widget-item {
  margin-left: var(--homey-su-2);
  padding: var(--homey-su-4)
}

To align the elements on the edges of your the widget to other widgets, we offer the following classes:

CSS Class Purpose

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.

.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) to your widget:

<body class="homey-widget">
  <!-- Content of you widget here. -->
</body>

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):

<body class="homey-widget-small">
  <!-- Content of you widget here. -->
</body>

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

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.

.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.

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).

Table of combinations for font size and font weight

The image below shows several combinations used in widgets.

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

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`

--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) to find the appropriate font weight for your chosen font size.

CSS Variable Value Purpose

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.

--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 & Dark Mode) and fits nicely on a background with --homey-background-color (see Background color).

For use on different backgrounds or different purposes, we offer the following semantic color variables (see Semantic).

CSS Variable Purpose

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.

--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

<p class="my-custom-text">HELP ME!</p>

.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

CSS Class	Purpose
`.homey-text-align-left`	Align text left.
`.homey-text-align-center`	Align text center.
`.homey-text-align-right`	Align text right.

.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

CSS Class	Purpose
`.homey-dark-mode`	Force widget to dark mode independent of user settings.

.homey-dark-mode

Force widget to dark mode independent of user settings.

Usage Example

<body class="homey-widget homey-dark-mode">
  <!-- Content of you widget here. -->
</body>

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).

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).

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.

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). 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

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.

--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, Text Color, Lines & Borders and Icons 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

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.

.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):

CSS Variable Purpose

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.

--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

CSS Variable	Purpose
`--homey-line`	Used for most lines.
`--homey-line-light`	Used for light lines that should stand out less.

--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

CSS Variable	Purpose
`--homey-border-radius-small`	Only use where the default border radius is too big.
`--homey-border-radius-default`	Default border radius.

--homey-border-radius-small

Only use where the default border radius is too big.

--homey-border-radius-default

Default border radius.

Usage Example

<div class="my-custom-item"></div>

.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).

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

<div class="homey-custom-icon-example"></div>

.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):

CSS Variable Purpose

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.

--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

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.

--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

<div class="homey-custom-icon-example"></div>

.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

CSS Class	Purpose
`.homey-table`	Default table styling.
`.homey-table-striped`	Used for tables with only a few columns.

.homey-table

Default table styling.

.homey-table-striped

Used for tables with only a few columns.

To change the text alignment in the cells of the table, you can apply the text alignment classes (see Text Alignment) to the table element.

Usage Example

    <table class="homey-table text-align-center">
      <thead>
      <tr>
        <th>Header 1</th>
        <th>Header 2</th>
        <th>Header 3</th>
      </tr>
      </thead>
      <tbody>
      <tr>
        <td>Row 1, Cell 1</td>
        <td>Row 1, Cell 2</td>
        <td>Row 1, Cell 3</td>
      </tr>
      <tr>
        <td>Row 2, Cell 1</td>
        <td>Row 2, Cell 2</td>
        <td>Row 2, Cell 3</td>
      </tr>
      <tr>
        <td>Row 3, Cell 1</td>
        <td>Row 3, Cell 2</td>
        <td>Row 3, Cell 3</td>
      </tr>
      </tbody>
    </table>

PreviousSettings NextDebugging

Last updated 1 month ago

Widget

Title

Frame

Background color

Spacing

Space Units

Usage Example

Widget Padding

Usage Examples

Text

Text Presets

Usage Example

Variables

Table of combinations for font size and font weight

Font Size

Line Height

Font Weight

Text Color

Usage Example

Text Alignment

Colors

Light & Dark Mode

Usage Example

Palette

Semantic

Lines & Borders

Borders

Lines

Border Radius

Usage Example

Icons

Custom Icons

Usage Example

Variables

Usage Example

Tables

Usage Example

Widget

Title

Frame

Background color

Spacing

Space Units

Usage Example

Widget Padding

Usage Examples

Text

Text Presets

Usage Example

Variables

Table of combinations for font size and font weight

Font Size

Line Height

Font Weight

Text Color

Usage Example

Text Alignment

Colors

Light & Dark Mode

Usage Example

Palette

Semantic

Lines & Borders

Borders

Lines

Border Radius

Usage Example

Icons

Custom Icons

Usage Example

Variables

Usage Example

Tables

Usage Example