Box

import "@taprootio/espalier/box";

<esp-box>

Used as a base to group context visually. esp-box has a css part of box that can be styled to create cards, forms, and other UI elements.

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.

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.

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 var(--esp-color-layer-2).

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

Box