Skip to main content

x-box

A utility custom element that accepts shorthand attributes for spacing, sizing, layout, flex-child control, and visual styling — no CSS class names required.

Quick start 
import { registerLayoutElements } from "mates-ui";
registerLayoutElements();




// In a template:
html`<x-box p="2" bgcolor="var(--md-color-primary-muted)" br="var(--md-radius-md)">
  ${Text("Hello", { type: "body-sm" })}
</x-box>`

Spacing and surface

import { html, renderApp } from 'mates';
import { Text, registerLayoutElements } from 'mates-ui';
registerLayoutElements();

const App = () => () => html`
<x-box p="2" bgcolor="var(--md-color-primary-muted)" br="var(--md-radius-md)">
${Text("This box has p=2 (16 px padding), primary-muted background, and rounded corners.", { type: "body-sm" })}
</x-box>
`;

renderApp(App, document.getElementById('app'));

Constrained centered container

import { html, renderApp } from 'mates';
import { Text, registerLayoutElements } from 'mates-ui';
registerLayoutElements();

const App = () => () => html`
<x-box w="100%" maxw="400px" mx="auto" p="3"
bgcolor="var(--md-surface-card)" br="var(--md-radius-lg)" shadow="var(--md-shadow-sm)">
${Text("Centered card — maxw=400px, mx=auto, p=3 (24 px)", { type: "body-sm" })}
</x-box>
`;

renderApp(App, document.getElementById('app'));

Flex child control

import { html, renderApp } from 'mates';
import { Text, registerLayoutElements } from 'mates-ui';
registerLayoutElements();

const App = () => () => html`
<div style="display:flex;gap:8px;width:100%;max-width:32rem;">
<x-box p="1" bgcolor="var(--md-color-primary-muted)" br="var(--md-radius-sm)">
${Text("Fixed", { type: "label-sm" })}
</x-box>
<x-box p="1" grow="1" bgcolor="var(--md-color-secondary-muted)" br="var(--md-radius-sm)">
${Text("grow=1 — fills remaining space", { type: "label-sm" })}
</x-box>
<x-box p="1" bgcolor="var(--md-color-primary-muted)" br="var(--md-radius-sm)">
${Text("Fixed", { type: "label-sm" })}
</x-box>
</div>
`;

renderApp(App, document.getElementById('app'));

x-box

import { registerLayoutElements } from "mates-ui"; registerLayoutElements();
Prop Type Default Description
attr AttrMap — HTML attributes on the root element.
basis CSS length — Sets flex-basis.
bgcolor / bg CSS color value — Sets the background-color.
border CSS border value — Sets the border shorthand.
box-sizing "border-box" | "content-box" — Sets box-sizing.
classes string | string[] — Extra root classes — joined and appended after built-in classes.
color CSS color value — Sets the foreground text color.
cursor CSS cursor value — Sets the cursor style.
data DataAttrMap — Root `data-*` map (`testId` → `data-testid`). `testId` prop / `attr` win over `data`.
display CSS display value — Sets the CSS display property.
flex CSS flex value — Sets the flex shorthand.
fs / font-size CSS length — Sets font-size.
fw / font-weight number | string — Sets font-weight.
gap CSS length — Sets the gap when x-box itself is a flex/grid container.
grow number — Sets flex-grow.
h / height CSS length — Sets the height of the element.
id string — Root `id` shorthand (`attr.id` wins). Form native-control `id` props are unchanged.
lh / line-height number | CSS length — Sets line-height.
m / mt / mb / ml / mr number | CSS length — Margin shorthands. Number × 8px or raw CSS.
minh / maxh CSS length — min-height / max-height.
minw / maxw CSS length — min-width / max-width.
mx / my number | CSS length — Horizontal / vertical margin shorthands.
on OnEventMap — DOM event handlers on the root element.
opacity number — Sets opacity (0–1).
order number — Sets the flex / grid order.
overflow / overflow-x / overflow-y CSS overflow value — Controls overflow behaviour.
p / pt / pb / pl / pr number | CSS length — Padding shorthands. Number × 8px or raw CSS.
position CSS position value — Sets the CSS position property.
px / py number | CSS length — Horizontal / vertical padding shorthands.
radius / br / border-radius CSS length — Sets border-radius.
self / align-self CSS align-self value — Aligns this child along the cross axis.
shadow / box-shadow CSS shadow value — Sets box-shadow.
shrink number — Sets flex-shrink.
style StyleMap — Inline CSS on the root element.
ta / text-align CSS text-align value — Sets text-align.
top / right / bottom / left CSS length — Inset shorthands for positioned elements.
w / width CSS length — Sets the width of the element.
ws / white-space CSS white-space value — Sets white-space.
z / z-index number — Sets the z-index.