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.

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

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

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`