Defines how a solid surface looks — a base color, plus how that color responds to light and space — as a reusable resource many objects can share.
JavaScript API:
PlainMaterial
This is the member of the Material family: like every material it is a
reusable, standalone definition of a surface's appearance, referenced by the
paints that apply it; here it gives a solid surface a base color enriched by an
optional tonemap, color-source, and field. Because the material is shared by id,
animating it updates every object that references it at once.
Key attributes. base-color is the flat surface color. tonemap references
a sk-tonemap that recolors the surface by light (shadow-to-light hues);
base-color-source references a ColorSource that varies the base color
by space. base-color-darken-factor controls how much shadows darken when no
tonemap is present. field is an optional spatial mask for per-fragment alpha —
a scene-resident field, shareable with other consumers so one <sk-animation> on
it drives them all together. When a tonemap and a color-source are present,
tonemap-blend-mode (default multiply, so the tonemap tints the base color)
and base-color-source-blend-mode (default normal, so the source defines the
base color where it applies) choose how each composites over the base, and
color-interpolation selects the space that blending happens in.
Related. It is put on an object by the Paint family —
sk-surface-paint, sk-edge-paint, sk-stroke-paint — which
name it with material="#id". Its color inputs are a sk-tonemap (by
light) and a sk-color-map-source or other ColorSource (by space).
Serve these docs to run the live example.
WebGPU needs a secure context — open this page via grunt serve
rather than double-clicking the file. The Markup tab works from disk.
<!-- Two materials on two spheres. LEFT: a plain flat material whose base color
ANIMATES cyan to magenta, shaded only by the light — watch its hue pulse.
RIGHT: a white material driven by a dark-red -> gold tonemap, so shadow reads
red and light reads gold (white base, so the ramp colors show literally).
Both materials are scene-resident and referenced by id from a surface paint. -->
<sk-scene>
<sk-directional-light p="42deg" h="25deg" intensity="1.0"></sk-directional-light>
<sk-ambient-light intensity="0.4"></sk-ambient-light>
<!-- Flat material with an animated base color (no tonemap). -->
<sk-plain-material id="pulse" base-color="cyan">
<sk-animation duration="2000ms" iterations="Infinity" direction="alternate">
<sk-keyframe offset="0" base-color="cyan"></sk-keyframe>
<sk-keyframe offset="1" base-color="magenta"></sk-keyframe>
</sk-animation>
</sk-plain-material>
<!-- A tonemap (different shadow/light hues), referenced by id. -->
<sk-ramp-color-map id="ramp__cm">
<sk-color-stop stop-offset="0" stop-color="darkred"></sk-color-stop>
<sk-color-stop stop-offset="1" stop-color="gold"></sk-color-stop>
</sk-ramp-color-map>
<sk-tonemap id="tm" color-map="#ramp__cm"></sk-tonemap>
<!-- White material referencing the tonemap, so the ramp reads literally. -->
<sk-plain-material id="fancy" base-color="white" tonemap="#tm"></sk-plain-material>
<sk-sphere x="-1.5" segments="6"><sk-surface-paint material="#pulse"></sk-surface-paint></sk-sphere>
<sk-sphere x="1.5" segments="6"><sk-surface-paint material="#fancy"></sk-surface-paint></sk-sphere>
</sk-scene>| Attribute | Type | Default | Description |
|---|---|---|---|
id |
<id> |
— | The element's unique identifier — the standard HTML global id attribute. |
base-coloranimatable |
<color> |
— | The base surface color. |
base-color-darken-factoranimatable |
<number> |
— | Controls how much the base color darkens in shadow when no tonemap is provided. |
tonemapanimatable |
<id-ref> |
— | Optional tonemap that defines the lighting response. reference by id |
tonemap-blend-modeanimatable |
<blend-mode> ("normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity" | "plus-lighter") |
"multiply" |
CSS blend mode for combining the tonemap output with baseColor. |
base-color-sourceanimatable |
<id-ref> |
— | Gets the base-color-source, resolving a source-less material to the reference by id |
base-color-source-blend-modeanimatable |
<blend-mode> ("normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity" | "plus-lighter") |
"normal" |
The blend mode used when a baseColorSource composites over the flat |
color-interpolation |
<blend-color-interpolation> ("auto" | "srgb" | "srgb-linear") |
"auto" |
The color space this material's compositing blends run in — the |
backdrop-blend-modeanimatable |
<backdrop-blend-mode> ("normal" | "multiply" | "screen" | "plus-lighter") |
"normal" |
How this material's final RGBA blends across the material↔BACKDROP |
fieldanimatable |
<id-ref> |
— | Optional field that controls fragment alpha (opacity masking). reference by id |
Optional tonemap child referencing a color-map (ramp / ordered-dither / blue-noise / halftone / composite).
Used in guides: Scene basics