Box
import "@taprootio/espalier/box";
<esp-box>
Groups related content in a themed container. Style its box CSS part
to create cards, forms, or other grouped regions.
A field fills one layer above the surface it sits on.
Use surface-layer="1|2|3|4" to select the default painted layer.
What esp-box is not: a full-bleed page band. The box is a card —
it paints its own raised surface (--esp-color-layer-1), carries
padding, and fills its container's height. A band is
esp-section: it paints the local canvas edge
to edge with a centered well and hosts a theme zone (context="…")
with nothing to neutralize. Keep boxes for what they are for — cards,
panels, and form surfaces — and replace any pre-3.2 "neutralized box"
band with a bare section.
Select a raised form surface with surface-layer; fields follow it automatically.
Slots
<esp-box> has a slot:
Default
The default slot holds elements to display in the box.
Attributes
<esp-box> has the following attributes:
full-screen
full-screen has a default value of false.
Whether the box should take up the full screen. Useful when displaying a dialog in full-screen mode.
A full-screen box fills the viewport. Inside a
bounded dialog it fills exactly the dialog's
rectangle instead: it takes its position and size from the same
--esp-dialog-inset-* custom properties, set on the esp-dialog or any
ancestor of the box.
surface-layer
surface-layer has a default value of undefined.
Declares the painted surface depth. Fields use the next local layer, capped at layer 4.
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-box> has the following methods:
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
CSS Parts
<esp-box> has a CSS part:
box
The box element. The default style is a padded element displayed as a box. Style the CSS part to create cards, forms, and other UI elements. Here is a card style:
CSS Properties
<esp-box> has the following CSS properties:
--esp-color-box-background
The background color of the box.
--esp-box-background
Adds a layer in the background of the box. Intended for background images or gradients.
--esp-box-background-opacity
The opacity of the background layer.
--esp-size-box-padding
The padding inside the box.
--esp-box-shadow
The box's drop shadow. Defaults to the theme's --esp-shadow-1 elevation.
--esp-field-background
Background color of the shared field shell. Defaults to one layer above the nearest declared surface, capped at var(--esp-color-layer-4), or var(--esp-color-layer-2) without a declared surface. An explicit override wins.
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).