---
title: "Materials"
description: "Make the parts your widget draws itself match the home's material, with the --material-* variables and useMaterial()."
canonical: https://glasshome.app/docs/widgets/widget-sdk/materials
section: "SDK"
updated: 2026-10-04
---
# Materials

Each home picks a material in its theme: Glass, Frosted, Paper, Neon, Chalk, or one somebody made in the creator studio. It decides what every card and control looks like. A widget built from `<Widget>` and the SDK's parts already matches it. This page is for the parts you draw yourself, like a key, a slot or a glow, so they match too.

> **SDK 1.21 and up:** The variables and useMaterial() on this page need SDK 1.21. Raise your manifest's sdkVersion floor to it. Dashboards have them from GlassHome 1.4.0-beta.11.

## The material variables

Every `--material-*` variable is yours to read. Every material sets them, in light and dark mode.

| Variable                   | What it is                                                                     |
| -------------------------- | ------------------------------------------------------------------------------ |
| `--material-accent`        | The color for what is on. The theme's accent, unless the material has its own. |
| `--material-face`          | The background of a part that stands out: a key, a knob.                       |
| `--material-well`          | The background of a part that sits in: a track, a slot.                        |
| `--material-raised`        | The `box-shadow` for a part that stands out.                                   |
| `--material-pressed`       | The inset `box-shadow` for a part that sits in.                                |
| `--material-control-track` | An empty control, like a switch that is off.                                   |
| `--material-control-fill`  | The lit part of a control, like a switch that is on.                           |
| `--material-control-knob`  | The knob on a lit control.                                                     |
| `--material-blur`          | How much the glass blurs what is behind it, as a length.                       |
| `--material-clarity`       | How much of the card color the glass keeps, as a percentage.                   |
| `--material-tint`          | How strongly a card takes its own color, as a number.                          |
| `--material-glow`          | How far the glow reaches, as a length.                                         |

Two more belong to your widget rather than the material: `--surface-tone` is your widget's own color, and `--surface-wash` is how strongly it tints the card.

```css
.key {
  background: var(--material-face);
  box-shadow: var(--material-raised);
}
.key[data-on] {
  background: var(--material-control-fill);
  color: white;
}
.slot {
  background: var(--material-well);
  box-shadow: var(--material-pressed);
}
```

On Glass and Paper the two shadows are faint. On a material with a raised face they carry the whole look, so the same CSS fits both.

## Changing what you draw by material

`useMaterial()` tells you which material the home has, with every setting filled in. Use it for decisions, like leaving out a glow on a material without one, and keep the colors in CSS.

```tsx
import { useMaterial } from "@glasshome/widget-sdk";

function Meter() {
  const material = useMaterial();
  return (
    <div classList={{ "meter-glow": material().terms.glow > 0 }}>
      {/* ... */}
    </div>
  );
}
```

| Field          | Meaning                                        |
| -------------- | ---------------------------------------------- |
| `id`           | Which material it is.                          |
| `terms.face`   | `"flat"` or `"raised"`.                        |
| `terms.glow`   | How far the glow reaches, in px; 0 means none. |
| `terms.accent` | `"theme"`, or the material's own color.        |
| `terms.*`      | Every other setting the creator studio shows.  |

On a dashboard older than GlassHome 1.4.0-beta.11, it gives you Glass.

## Names not to read

- `--glass-*` are the knobs you set on a `.glass` element, like `--glass-base`. Setting them is fine; reading them is not, because they change whenever the glass does.
- Names that start with `--_`, like `--_material-edge`, are how the material is drawn inside. Leave them alone.
- A few older `--material-*` names are retired: `--material-depth`, `--material-hue`, `--material-reach`, `--material-ink`, `--material-ink-level`, `--material-ink-lift`, `--material-edge-width`, `--material-edge-ink` and `--material-edge-accent`. Some widgets read them before 1.21, and they still work. SDK 2.0 will remove them (see [Coming in 2.0](/docs/widgets/changelog#coming-in-20-breaking)).

`bun widget build` warns about each of these reads and names the replacement:

| If you read                                                | Use                                                                               |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `--glass-tone`, `--material-hue`                           | `--surface-tone`, or `--material-accent` when your widget has no color of its own |
| `--glass-wash`, `--glass-wash-2`                           | `--surface-wash`                                                                  |
| `--glass-rim-shine`, `--glass-lift`, `--material-depth`    | `--material-raised` or `--material-pressed`                                       |
| `--material-reach`, `--material-edge-*`, `--material-ink*` | `useMaterial().terms`                                                             |