API reference — BMX Web Components

`<bmx-accordion>`

Properties

Property	Attribute	Type	Default	Description
`appearance`	`appearance`	`BmxAccordionAppearance`	`'bordered'`	How the accordion is drawn.
`collapsible`	`collapsible`	`boolean`	`true`	Whether the open panel may be closed again, leaving none. Only asked when one panel may be open. False is the right shape for a wizard, where something must always be showing; true is the right shape for a list of questions, where closing the answer you have read is the obvious thing to try.
`expanded`	property only	`string[]`	`[]`	Which panels are open, by value. Mutable, so pressing a heading updates it. Seeded from whichever items were written with `open` when the accordion first reads its children, and made legal on the way in: values naming nothing are dropped, and several open items in a single-open accordion keep the first in document order. Accepts a comma-separated or JSON string as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`headingLevel`	`heading-level`	`number`	`3`	The `aria-level` every item's heading is given.
`multiple`	`multiple`	`boolean`	`false`	Whether more than one panel may be open. The default is one at a time, which is what makes it an accordion rather than a list of disclosures - and what a long page of sections usually wants, because it keeps the headings within reach of each other.

Events

Event	Detail	Description
`bmxChange`	`BmxAccordionChangeDetail`	Fired when a panel opens or closes.

Methods

Method	Signature	Description
`closeAll`	`closeAll() => Promise<void>`	Close every panel. Ignored when one must always be showing.
`closePanel`	`closePanel(value: string) => Promise<void>`	Close a panel by value.
`openAll`	`openAll() => Promise<void>`	Open every panel. Ignored unless several may be open.
`openPanel`	`openPanel(value: string) => Promise<void>`	Open a panel by value, closing another if only one may be open.

Slots

Slot	Description
`(default)`	`bmx-accordion-item` elements.

CSS shadow parts

Part	Description
`base`	The container.

CSS custom properties

Property	Description
`--bmx-accordion-background`	Background behind the sections.
`--bmx-accordion-border-color`	Colour of the rules between sections.
`--bmx-accordion-gap`	Space between sections in the separated appearance.
`--bmx-accordion-radius`	Corner radius of the container, or of each section when separated.

`<bmx-accordion-item>`

Properties

Property	Attribute	Type	Default	Description
`badge`	`badge`	`string`	—	A short count or status, rendered after the heading text.
`disabled`	`disabled`	`boolean`	`false`	Whether it can be opened.
`heading`	`heading`	`string`	—	The heading's text.
`headingLevel`	`heading-level`	`number`	`3`	The heading level this section sits at, as `aria-level`. Set by `bmx-accordion` from its own `heading-level` so a whole accordion is consistent; set it here when using an item on its own.
`icon`	`icon`	`string`	—	An inline SVG string, rendered before the heading text.
`open`	`open`	`boolean`	`false`	Whether the panel is showing. Mutable, so pressing the heading changes it. Inside a `bmx-accordion` the accordion owns this - it is the thing that knows whether another panel has to close first - and writes it on every item.
`value`	`value`	`string`	—	What this item is identified by in the accordion's `expanded` and in events. Falls back to the heading and then to its position, so a set of items written with headings alone still reports something distinguishable.

Events

Event	Detail	Description
`bmxToggle`	`BmxAccordionToggleDetail`	Fired when the item opens or closes.

Methods

Method	Signature	Description
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus this item's heading button.
`toggle`	`toggle() => Promise<void>`	Open or close it, as pressing the heading would.

Slots

Slot	Description
`(default)`	The panel's content.
`heading`	Rich heading content, in place of the `heading` property.

CSS shadow parts

Part	Description
`badge`	The badge after it.
`content`	The clipping box inside the panel. Its padding is on an inner element, so that a closed panel collapses to nothing.
`header`	The element carrying `role="heading"`.
`icon`	The icon before the heading text.
`marker`	The chevron that turns.
`region`	The panel.
`trigger`	The button inside it.

CSS custom properties

Property	Description
`--bmx-accordion-heading-font-size`	Size of the heading text.
`--bmx-accordion-heading-weight`	Weight of the heading text.
`--bmx-accordion-hover`	Background of a heading under the pointer.
`--bmx-accordion-marker-size`	Size of the chevron.
`--bmx-accordion-padding-block`	Space inside the heading, down.
`--bmx-accordion-padding-inline`	Space inside the heading and the panel, across.

`<bmx-avatar>`

Properties

Property	Attribute	Type	Default	Description
`alt`	`alt`	`string`	—	What the image is announced as, when it should not be the name. Rarely needed: an avatar is a picture of the person named beside it, so the name is the right text almost always.
`decorative`	`decorative`	`boolean`	`false`	Hide the avatar from assistive technology. Set it when the person's name is already written beside the picture, which is most lists. See the note above - this is the one decision here that the component genuinely cannot make for the consumer.
`loading`	`loading`	`'lazy' \| 'eager'`	`'lazy'`	Whether the browser may defer loading the photograph.
`name`	`name`	`string`	—	The person's name. The initials, the tint and the announcement all come from it.
`seed`	`seed`	`string`	—	What the tint is derived from, when it should not be the display name. A user id is the better seed in any application where people can rename themselves: `name` changes when somebody marries and their colour changes with it, which is exactly the thing a derived colour was supposed to stop.
`shape`	`shape`	`BmxAvatarShape`	`'circle'`	A circle, or a rounded square.
`src`	`src`	`string`	—	A photograph. Falls back to the initials if it fails to load.

Slots

Slot	Description
`(default)`	A custom fallback, used in place of the anonymous glyph.
`badge`	A `bmx-badge` pinned to the corner: presence, a count, a state.

CSS shadow parts

Part	Description
`badge`	The corner the badge slot sits in.
`icon`	The anonymous glyph, when there is not even a name.
`image`	The photograph.
`initials`	The letters drawn when there is no photograph.

CSS custom properties

Property	Description
`--bmx-avatar-color`	The fallback background, overriding the derived tint.
`--bmx-avatar-font-size`	The initials, relative to the avatar by default.
`--bmx-avatar-font-weight`	How heavy the initials are.
`--bmx-avatar-radius`	The corner radius in `square` shape.
`--bmx-avatar-ring`	The ring drawn round the edge. `none` removes it.
`--bmx-avatar-size`	The diameter, or the side of the square.
`--bmx-avatar-text`	The colour of the initials and the glyph.
`--bmx-avatar-tone-0`	The first tint of the derived palette.
`--bmx-avatar-tone-1`	The second.
`--bmx-avatar-tone-2`	The third.
`--bmx-avatar-tone-3`	The fourth.
`--bmx-avatar-tone-4`	The fifth.
`--bmx-avatar-tone-5`	The sixth.
`--bmx-avatar-tone-6`	The seventh.
`--bmx-avatar-tone-7`	The eighth.

`<bmx-avatar-group>`

Properties

Property	Attribute	Type	Default	Description
`decorative`	`decorative`	`boolean`	`false`	Hide the whole stack from assistive technology, when the names are listed beside it.
`items`	property only	`BmxAvatarEntry[]`	`[]`	The people, as data. Read through `src/core/markup.ts`, so an `items='[{"name":"Ada"}]'` attribute written by a server-side template is the list it looks like rather than a string the component tries to map over.
`label`	`label`	`string`	—	What the stack is: "Assigned to", "Attending", "Editors".
`max`	`max`	`number`	—	The most faces to draw before the rest become a counter. Never hides exactly one.
`moreLabel`	`more-label`	`string`	—	The counter's accessible name, when the composed one is not wanted.

Slots

Slot	Description
`(default)`	`bmx-avatar` elements.

CSS shadow parts

Part	Description
`group`	The row.
`more`	The counter.

CSS custom properties

Property	Description
`--bmx-avatar-group-more-background`	The fill of the counter.
`--bmx-avatar-group-more-color`	The text on it.
`--bmx-avatar-group-overlap`	How far each avatar sits over the one before it.
`--bmx-avatar-group-ring`	The ring that separates one avatar from the next.

`<bmx-badge>`

Properties

Property	Attribute	Type	Default	Description
`dot`	`dot`	`boolean`	`false`	Draw a mark with no number in it. Then `label` is not optional: a dot with nothing to say is a decoration, and this component makes it one - `aria-hidden`, out of the tree entirely.
`for`	`for`	`string`	—	The `id` of the control this badge belongs to. The badge writes `aria-describedby` on it, so the count is announced as part of that control rather than as a loose number beside it. The control must be in the same document or shadow root as the badge, which is what an ID reference means everywhere in the platform.
`label`	`label`	`string`	—	What is being counted: `unread messages`, `items in your basket`. It reaches the announcement and never the bubble. Without it a screen reader is given a bare number, which is the accessible equivalent of a red dot with no explanation.
`max`	`max`	`number`	`99`	The largest count drawn in full. Past it the bubble shows `99+`, and the exact number is still announced.
`placement`	`placement`	`BmxBadgePlacement`	`'top-end'`	Where the bubble sits over slotted content.
`showZero`	`show-zero`	`boolean`	`false`	Draw a count of zero instead of nothing.
`tone`	`tone`	`BmxBadgeTone`	`'neutral'`	What the badge is reporting. Meaning, not colour: the colours are custom properties.
`value`	`value`	`number \| string`	—	The count, or a short word. A string of digits is treated as the count it is, because `value="3"` from a Razor page or an htmx swap is the commonest way this is ever set.

Slots

Slot	Description
`(default)`	Something for the bubble to sit on. Not a focusable control - see above.

CSS shadow parts

Part	Description
`anchor`	The box the slotted content sits in.
`badge`	The bubble.

CSS custom properties

Property	Description
`--bmx-badge-background`	The bubble's fill, overriding the tone.
`--bmx-badge-border`	The ring that separates the bubble from what it sits on.
`--bmx-badge-color`	The text on it.
`--bmx-badge-dot-size`	The diameter of the `dot` form.
`--bmx-badge-font-size`	The digits.
`--bmx-badge-font-weight`	How heavy they are.
`--bmx-badge-height`	The bubble's height, and its diameter when it holds one digit.
`--bmx-badge-offset`	How far the bubble hangs off the corner of slotted content.
`--bmx-badge-padding-inline`	The room either side of a longer count or a word.
`--bmx-badge-radius`	The corner radius. A pill by default.
`--bmx-badge-tone-danger`	The fill for `tone="danger"`.
`--bmx-badge-tone-info`	The fill for `tone="info"`.
`--bmx-badge-tone-neutral`	The fill for `tone="neutral"`.
`--bmx-badge-tone-success`	The fill for `tone="success"`.
`--bmx-badge-tone-warning`	The fill for `tone="warning"`.
`--bmx-badge-tone-warning-text`	The text on the warning fill, which is dark rather than white.

`<bmx-breadcrumb>`

Properties

Property	Attribute	Type	Default	Description
`collapse`	`collapse`	`'auto' \| 'never'`	`'auto'`	Whether crumbs that do not fit collapse behind a button.
`label`	`label`	`string`	`'Breadcrumb'`	The trail's accessible name. It names the landmark, so it is what a screen-reader user hears when they jump between the navigation regions of a page. "Breadcrumb" is right for the only one on a page and wrong for the second.
`markCurrent`	`mark-current`	`boolean`	`true`	Whether the last crumb is marked as the page you are on. The single most useful thing this component does for a screen reader: without `aria-current="page"` a trail is a row of links, and the one saying where you are is indistinguishable from the ones saying where you could go.
`menuLabel`	`menu-label`	`string`	`'Show the rest of the path'`	The overflow button's accessible name.
`separator`	`separator`	`string`	`'/'`	What is drawn between two crumbs. Text rather than an image, because a separator is punctuation: it has to match the typeface around it, and a customer whose house style uses `>` or `»` or a middle dot has to be able to say so without forking anything. It reaches the crumbs as `--bmx-breadcrumb-separator-content`, so a stylesheet can change it for one trail without touching the markup.

Events

Event	Detail	Description
`bmxSelect`	`BmxBreadcrumbSelectDetail`	Fired when a crumb is chosen from the overflow menu.

Methods

Method	Signature	Description
`refresh`	`refresh() => Promise<void>`	Re-measure now. Rarely needed: a resize and a change of children are watched.

Slots

Slot	Description
`(default)`	The crumbs, in order, root first.

CSS shadow parts

Part	Description
`base`	The `<nav>`.
`list`	The list inside it.
`menu`	The overflow menu's surface.
`separator`	The mark drawn before the trigger.
`trigger`	The button the collapsed crumbs hide behind.

CSS custom properties

Property	Description
`--bmx-breadcrumb-gap`	Space between a separator and the crumb either side of it.
`--bmx-breadcrumb-separator-content`	The mark drawn between two crumbs. Set from the `separator` property; override it for a house style.
`--bmx-breadcrumb-trigger-color`	The overflow button's colour.
`--bmx-breadcrumb-trigger-radius`	The overflow button's corner radius.

`<bmx-breadcrumb-item>`

Properties

Property	Attribute	Type	Default	Description
`current`	`current`	`boolean`	`false`	Whether this is the page being looked at. Draws as text and marks it.
`href`	`href`	`string`	—	Where the crumb goes. Leave it off for the page you are on, or to wrap your own link.
`label`	`label`	`string`	—	What the overflow menu calls this crumb. Defaults to its text.
`rel`	`rel`	`string`	—	The link's `rel`. `noreferrer` is added to anything opening in a new tab that has not said otherwise, because `target="_blank"` without it hands the opened page a `window.opener` it can navigate - the same hardening `bmx-button` does in anchor mode, and for the same reason.
`target`	`target`	`string`	—	The link's target, when there is a link.

Methods

Method	Signature	Description
`activate`	`activate() => Promise<void>`	Follow this crumb, as though it had been clicked. What the parent calls when the crumb is chosen from the overflow menu. The click lands on the real link, so a router that intercepted it still intercepts it and a handler the author attached still runs - there is no second navigation path to keep in step with the first.
`getLabel`	`getLabel() => Promise<string>`	The crumb's name, for the parent's overflow menu.

Slots

Slot	Description
`(default)`	The crumb's label.
`prefix`	An icon before the label.

CSS shadow parts

Part	Description
`base`	The link, or the text that stands in for it.
`label`	The label text.
`prefix`	The icon slot's wrapper.
`separator`	The mark drawn before the crumb.

CSS custom properties

Property	Description
`--bmx-breadcrumb-color`	A link crumb's colour.
`--bmx-breadcrumb-color-hover`	A link crumb's colour under the pointer.
`--bmx-breadcrumb-current-color`	The colour of the crumb you are on.
`--bmx-breadcrumb-gap`	Space between a separator and the crumb either side of it.
`--bmx-breadcrumb-radius`	The corner radius of a crumb's focus ring and hover shape.
`--bmx-breadcrumb-separator-color`	The separator's colour.
`--bmx-breadcrumb-separator-content`	The mark drawn before a crumb. Set by the parent's `separator` property; override it for a house style.

`<bmx-button>`

Properties

Property	Attribute	Type	Default	Description
`action`	property only	`(event: BmxButtonActivateDetail) => unknown \| Promise<unknown>`	—	An async handler that drives the busy state. A property, not an attribute. Set it and the button becomes busy for the lifetime of the returned promise, refuses re-entry while it runs, and clears itself on both resolve and reject - which is the half everyone forgets, leaving a spinner on screen after a failed save.
`autoFocus`	`auto-focus`	`boolean`	`false`	Take focus on first render.
`badge`	`badge`	`string \| number`	—	A small counter or status badge rendered on the button's trailing corner.
`confirm`	`confirm`	`string`	—	Turn the button into a two-step confirmation. The first activation arms it and swaps the label for this text; the second fires. Cheaper than a modal for a destructive action on a row, and - unlike `window.confirm` - it does not steal focus or block the main thread.
`confirmTimeout`	`confirm-timeout`	`number`	`3000`	How long an armed button waits before disarming, in ms. Floored at 1000.
`controls`	`controls`	`string`	—	`aria-controls`: the id of the element this button controls.
`cooldown`	`cooldown`	`number`	`0`	Minimum gap between two activations, in ms. Guards against double-submit.
`describedBy`	`described-by`	`string`	—	`aria-describedby`: the id of an element that explains this button.
`disabled`	`disabled`	`boolean`	`false`	Disable the button.
`download`	`download`	`string`	—	Anchor download attribute.
`expanded`	`expanded`	`boolean`	—	`aria-expanded`, for a disclosure or menu trigger.
`focusableWhenDisabled`	`focusable-when-disabled`	`boolean`	`false`	Keep a disabled button focusable, marking it `aria-disabled` instead. WCAG 2.2 prefers this for controls inside a toolbar or a group: a natively disabled control vanishes from the Tab order, so a keyboard user never learns it exists, let alone why it is unavailable. Pair it with `describedBy` pointing at the explanation.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container.
`haspopup`	`haspopup`	`'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true'`	—	`aria-haspopup`, for a button that opens a menu, dialog or listbox.
`hideLabelBelow`	`hide-label-below`	`BmxBreakpoint`	—	Drop the visible label below this breakpoint, keeping the icon. The responsive escape hatch for toolbars: a row of five labelled actions that would wrap on a phone becomes a row of five icons instead. The label stays in the accessibility tree, so nothing is lost to a screen reader.
`hold`	`hold`	`number`	`0`	Require the button to be held for this many milliseconds. For the genuinely irreversible action. A progress track fills as the user holds, which makes the requirement discoverable rather than mysterious. Works from the keyboard too: hold Enter or Space.
`href`	`href`	`string`	—	Render as an anchor. Sets link keyboard semantics: Enter activates, Space does not.
`iconOnly`	`icon-only`	`boolean`	`false`	Render as icon-only. Usually inferred - a button with slotted icons and no label is icon-only without being told - but settable for the case where the label exists and should be visually hidden while remaining the accessible name.
`justify`	`justify`	`BmxJustify`	`'center'`	How content is packed when the button is wider than its content.
`label`	`label`	`string`	—	The accessible name. Required when the button is icon-only. When a visible label is present this overrides it for assistive technology, which is occasionally what you want ("Delete" on screen, "Delete invoice INV-2451" announced).
`loading`	`loading`	`boolean`	`false`	Show the busy state and block activation.
`loadingLabel`	`loading-label`	`'replace' \| 'keep'`	`'keep'`	Whether the busy state replaces the label or sits beside it.
`loadingText`	`loading-text`	`string`	`'Working…'`	Label announced and optionally shown while busy.
`name`	`name`	`string`	—	Submitted name, when this button is a form's submitter.
`pressed`	`pressed`	`boolean`	`false`	The toggle state. Ignored unless `toggle` is set.
`rel`	`rel`	`string`	—	Anchor rel. Merged with the automatic `noopener noreferrer` for `_blank`.
`ripple`	`ripple`	`BmxRipple`	`'none'`	The effect painted from the point of activation. `wave` is the familiar Material ripple; `rings` sends concentric rings outward; `spiral` unwinds an Archimedean spiral; `burst` fires spokes; `glow` blooms softly; `sweep` runs a highlight across the control; `echo` pulses a ring out past its edge. Tune any of them per button, or globally, without touching the component: `css bmx-button { --bmx-effect-duration: 900ms; --bmx-effect-color: #fff; --bmx-effect-opacity: 0.5; --bmx-effect-easing: cubic-bezier(0.16, 1, 0.3, 1); }` Off by default: a flourish should be opted into, and a page where every button animates is a page where none of them mean anything. Suppressed entirely under `prefers-reduced-motion`, and never rendered to assistive technology - it is decoration, and decoration only.
`rovingTabindex`	`roving-tabindex`	`number`	—	The tabindex applied to the rendered control. Managed by a parent `bmx-button-group` (or any other composite that implements a roving tabindex) and not normally set by hand. It exists as a property because the focusable element lives inside this component's shadow root, where a parent cannot reach it - and a composite widget that cannot take its children out of the tab order cannot implement the WAI-ARIA keyboard pattern at all.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment. `circle` is intended for icon-only buttons.
`size`	`size`	`BmxSize`	`'md'`	Size step.
`target`	`target`	`'_self' \| '_blank' \| '_parent' \| '_top'`	—	Anchor target. `rel` is hardened automatically for `_blank`.
`toggle`	`toggle`	`boolean`	`false`	Behave as a toggle, exposing `aria-pressed`.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role.
`type`	`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	Native button type. Ignored in link mode.
`value`	`value`	`string`	—	Submitted value, paired with `name`.
`variant`	`variant`	`BmxButtonVariant`	`'solid'`	Visual treatment.

Events

Event	Detail	Description
`bmxActivate`	`BmxButtonActivateDetail`	Fired when the button actually activates - after every guard has passed. The native `click` event still fires and still bubbles, so existing code keeps working; it is simply suppressed when a guard blocks or arms the button, which is the behaviour a consumer expects from `confirm` without having to write anything.
`bmxBusyChange`	`boolean`	Fired when the busy state changes, in either direction.
`bmxConfirmArm`	`void`	Fired when a confirming button arms itself, awaiting a second activation.
`bmxConfirmCancel`	`void`	Fired when an armed button disarms without activating.
`bmxHoldProgress`	`number`	Fired repeatedly while a press-and-hold is in progress, with a 0-1 fraction.
`bmxPressedChange`	`boolean`	Fired when the toggle state changes.

Methods

Method	Signature	Description
`activate`	`activate() => Promise<boolean>`	Activate the button programmatically, bypassing pointer and keyboard. Guards still apply: a programmatic activation of a confirming button arms it exactly as a click would. Anything else would make `confirm` a decoration rather than a guarantee.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the button.
`reset`	`reset() => Promise<void>`	Disarm a confirming button without activating it.
`setBusy`	`setBusy(value: boolean) => Promise<void>`	Set the busy state by hand, for a flow the `action` property cannot express.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Move focus to the button.

Slots

Slot	Description
`(default)`	The button's label.
`end`	Content after the label, typically an icon or chevron.
`loading`	Replaces the built-in spinner while busy.
`start`	Content before the label, typically an icon.

CSS shadow parts

Part	Description
`badge`	The counter badge.
`base`	The rendered `<button>` or `<a>`.
`end`	The trailing slot wrapper.
`hold`	The press-and-hold progress track.
`label`	The label wrapper.
`ripple`	A ripple instance.
`spinner`	The busy indicator.
`start`	The leading slot wrapper.

CSS custom properties

Property	Description
`--bmx-button-border-width`	Border width, for the outline variant.
`--bmx-button-font-size`	Label font size.
`--bmx-button-font-weight`	Label font weight.
`--bmx-button-gap`	Space between the icon and the label.
`--bmx-button-height`	The control's height. Defaults to the size step's height times the density scale.
`--bmx-button-icon-padding`	Horizontal padding of an icon-only button. Defaults to none.
`--bmx-button-icon-size`	Size of a slotted icon.
`--bmx-button-icon-width`	Width of an icon-only button. Defaults to its height, making it square.
`--bmx-button-padding-inline`	Horizontal padding.
`--bmx-button-radius`	Corner radius. Accepts the full four-value form, which is how a button group rounds only its outer corners.
`--bmx-effect-color`	What the click effect paints in. Defaults to the button's own text colour.
`--bmx-effect-duration`	How long the click effect runs.
`--bmx-effect-easing`	The click effect's timing curve.
`--bmx-effect-opacity`	The click effect's strength at its peak.

`<bmx-button-group>`

Properties

Property	Attribute	Type	Default	Description
`attached`	`attached`	`boolean`	`false`	Join the buttons into one continuous control, sharing their borders.
`disabled`	`disabled`	`boolean`	`false`	Disable every child. Children may still be disabled individually.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch the group, and its children equally, to the container width.
`label`	`label`	`string`	—	The group's accessible name. Not optional in practice: a toolbar announced as "group" with no name tells a screen reader user only that something has been grouped. Pass what the group is for - "Text alignment", "View mode".
`orientation`	`orientation`	`BmxOrientation`	`'horizontal'`	Layout direction. Also decides which arrow keys move focus.
`selection`	`selection`	`BmxButtonGroupSelection`	`'none'`	How many items may be selected.
`shape`	`shape`	`BmxShape`	—	Applied to every child that has not set its own.
`size`	`size`	`BmxSize`	—	Applied to every child that has not set its own.
`tone`	`tone`	`BmxTone`	—	Applied to every child that has not set its own.
`value`	`value`	`string \| null`	`null`	The selected value, in `single` mode. Two-way: the group writes back to it.
`values`	property only	`string[]`	`[]`	The selected values, in `multiple` mode. Two-way. Accepts a comma-separated or JSON string as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`variant`	`variant`	`BmxButtonVariant`	—	Applied to every child that has not set its own.
`wrap`	`wrap`	`boolean`	`false`	Allow the group to wrap onto more than one line.
`wrapFocus`	`wrap-focus`	`boolean`	`true`	Whether arrowing past the last item returns to the first.

Events

Event	Detail	Description
`bmxChange`	`BmxButtonGroupChangeDetail`	Fired when the selection changes. Not fired in `selection="none"`.

Methods

Method	Signature	Description
`refresh`	`refresh() => Promise<void>`	Re-read the children. Call after adding or removing items imperatively.
`setFocus`	`setFocus() => Promise<void>`	Move focus to the group's active item.

Slots

Slot	Description
`(default)`	`bmx-button` elements, or any focusable controls.

CSS shadow parts

Part	Description
`base`	The group container.

CSS custom properties

Property	Description
`--bmx-button-group-gap`	Space between items when the group is not attached.

`<bmx-calendar>`

Properties

Property	Attribute	Type	Default	Description
`agendaDays`	`agenda-days`	`number`	`30`	How many days the agenda covers.
`date`	`date`	`string`	—	The month or the day the view opens on, as `YYYY-MM-DD`. Assignable, so a page can drive the calendar from its own controls.
`dayEnd`	`day-end`	`string`	`'20:00'`	The last hour those views draw, as `HH:MM`.
`dayStart`	`day-start`	`string`	`'07:00'`	The first hour the week and day views draw, as `HH:MM`. A window rather than a whole day, because a diary that draws midnight to midnight spends two thirds of its height on hours nobody has meetings in. Events outside it are not dropped - they are clipped to the edge and drawn open, so the reader can see there is more.
`dragStep`	`drag-step`	`number`	`15`	The smallest move a drag makes, in minutes. Fifteen, because a diary is booked in quarter hours and a drag that lands on 09:37 is a drag the reader has to correct. A month view ignores it: the unit there is a day.
`dropFilter`	property only	`(detail: BmxCalendarChangeDetail) => boolean`	—	Whether a drop may land here, asked continuously while the drag moves. A page can always refuse a change afterwards by ignoring `bmxEventChange` - that is the one-way flow, and it works from every stack including the ones that can only write attributes. This is the other half: a rule the reader can see before they let go, so a block that may not go on a Sunday is drawn refused and announced as refused while it is still in their hand, rather than snapping back a moment after they thought they had put it somewhere. It is a function, so it is assigned from script - the React, Vue and Angular wrappers set properties and this arrives with them. A Razor or Blazor page that can only write attributes uses the event instead, and `src/core/markup.ts` refuses a string here rather than evaluating one. `js diary.dropFilter = ({ start }) => !start.endsWith('-13');`
`editable`	`editable`	`boolean`	`false`	Whether the reader may move and resize events. Off by default, because most calendars on most pages are a picture of a diary rather than a diary you can rearrange, and a component that let a reader drag a meeting the server will refuse has told them a lie. It is not `draggable`: that is a global HTML attribute with a meaning of its own, and a `@Prop()` of that name would fight the platform for it.
`events`	property only	`BmxCalendarEvent[]`	`[]`	The events. Read through `src/core/markup.ts`, so a JSON attribute written by a Razor page, a Blazor component or an htmx swap is the list it looks like rather than a string this component tries to map over. See defect 45.
`firstDayOfWeek`	`first-day-of-week`	`number`	—	Which day a week starts on, 0 for Sunday. Falls back to the locale's.
`label`	`label`	`string`	—	What this diary is. Announced as the grid's name.
`locale`	`locale`	`string`	—	The locale for month and weekday names. Falls back to the document's.
`maxPerDay`	`max-per-day`	`number`	`3`	The most events to draw in one month cell before the rest collapse.
`view`	`view`	`BmxCalendarFace`	`'month'`	Which face to draw.
`workingDays`	`working-days`	`number[] \| string`	`[]`	Which weekdays are working days, 0 for Sunday. Read through `src/core/markup.ts` as a comma-separated list, because `working-days="1,2,3,4,5"` is what a template can write.

Events

Event	Detail	Description
`bmxChange`	`{ readonly date: string; readonly view: BmxCalendarFace; }`	The view or the month changed.
`bmxDaySelect`	`BmxCalendarDayDetail`	A day was chosen.
`bmxEventChange`	`BmxCalendarChangeDetail`	An event was dropped somewhere new. Emitted once, on the drop - never while the pointer is moving. The component does not touch `events`: the page reassigns it and the calendar redraws, which is the one-way flow every other component here uses and the only shape that works from React, from Blazor and from a plain page at the same time. A page that ignores this event has a calendar whose blocks always snap back, which is the honest behaviour for a page that has not agreed to the change.
`bmxSelect`	`BmxCalendarEventDetail`	An event was chosen.

Methods

Method	Signature	Description
`next`	`next() => Promise<void>`	Move to the next month, or the next span of agenda days.
`previous`	`previous() => Promise<void>`	Move back.
`today`	`today() => Promise<void>`	Return to today.

Slots

Slot	Description
`empty`	Shown when there is nothing in view at all.

CSS shadow parts

Part	Description
`agenda`	The agenda list.
`agenda-day`	One day of it.
`allday`	One day's cell in the all-day strip.
`bar`	A multi-day event drawn across the week.
`column`	One day's column of timed events.
`day`	One day cell.
`daynumber`	The number inside it.
`entry`	One timed event inside a cell.
`grid`	The month grid.
`grip`
`header`	The bar with the month name and its controls.
`hour`	One hour rule across a column.
`live`
`more`	The "+2 more" control.
`now`	The line marking the current time.
`timegrid`	The week or day time grid.
`title`
`weekday`	One weekday heading.

CSS custom properties

Property	Description
`--bmx-calendar-bar-background`	The fill of a multi-day bar.
`--bmx-calendar-bar-color`	Its text.
`--bmx-calendar-bar-height`	How tall one bar is.
`--bmx-calendar-border`	The lines between days.
`--bmx-calendar-day-min-height`	How tall a day cell is at its shortest.
`--bmx-calendar-entry-background`	The fill of a timed event in a cell.
`--bmx-calendar-entry-color`	Its text.
`--bmx-calendar-focus-ring`	The focus indicator.
`--bmx-calendar-gutter`	How wide the hour rail down the side is.
`--bmx-calendar-hour-line`	The rule drawn across each hour.
`--bmx-calendar-hours-height`	How tall the whole time column is.
`--bmx-calendar-nonworking-background`	The fill behind a day outside working days.
`--bmx-calendar-now-color`	The line marking the current time.
`--bmx-calendar-outside-opacity`	How faint a day from a neighbouring month is.
`--bmx-calendar-radius`	The corner radius of the whole grid.
`--bmx-calendar-today-color`	The mark on today.
`--bmx-calendar-weekday-color`	The column headings.

`<bmx-carousel>`

Properties

Property	Attribute	Type	Default	Description
`autoplay`	`autoplay`	`boolean`	`false`	Move on its own. Never under `prefers-reduced-motion` - see above.
`hideControls`	`hide-controls`	`boolean`	`false`	Hide the previous and next controls, when the page provides its own.
`hideIndicator`	`hide-indicator`	`boolean`	`false`	Hide the dots or tablist.
`index`	`index`	`number`	`0`	The slide showing now, counting from 0. Assignable.
`interval`	`interval`	`number`	`5000`	How long each slide is shown, in milliseconds.
`label`	`label`	`string`	—	What this carousel is. A carousel with no name is announced as "carousel" and nothing else, which tells a reader that something is here and not what.
`loop`	`loop`	`boolean`	`false`	Whether the end wraps round to the beginning. Off by default: a carousel that silently returns to the first slide is one a reader cannot tell they have finished, and "have I seen all of these?" is the question this pattern is worst at answering.
`orientation`	`orientation`	`BmxOrientation`	`'horizontal'`	Which way it travels.
`perView`	`per-view`	`number`	`1`	How many slides are on screen at once.
`slideLabels`	`slide-labels`	`string[] \| string`	`[]`	A name for each slide. Used for the tab labels in `tabs` mode and for each slide's own accessible name in either. Without them a slide is announced as "3 of 12", which is a position rather than a description - true, and less than the author knows. Read through `src/core/markup.ts`, so a comma-separated or JSON attribute from a server-rendered template is the list it looks like.
`step`	`step`	`number`	—	How many slides one press of previous or next moves. Defaults to a full view.
`tabs`	`tabs`	`boolean`	`false`	Draw the picker as a real tablist rather than as an indicator. Only when each slide genuinely is a named destination. See the note above: the wrong one of these is a lie to a screen reader.

Events

Event	Detail	Description
`bmxAutoplayChange`	`BmxCarouselAutoplayDetail`	The clock started or stopped, and why.
`bmxChange`	`BmxCarouselChangeDetail`	The slide changed.

Methods

Method	Signature	Description
`goTo`	`goTo(index: number) => Promise<void>`	Go to a slide by its index.
`next`	`next() => Promise<void>`	Move to the next slide.
`pause`	`pause() => Promise<void>`	Stop the clock until `play()` or the pause control says otherwise.
`play`	`play() => Promise<void>`	Start the clock, if anything else will let it run.
`previous`	`previous() => Promise<void>`	Move to the previous slide.

Slots

Slot	Description
`(default)`	The slides. Anything at all; this component has no opinion about them.

CSS shadow parts

Part	Description
`dot`	One dot.
`frame`
`indicator`	The dots, or the tablist in `tabs` mode.
`next`	The control that steps forward.
`pause`	The autoplay control.
`previous`	The control that steps back.
`status`	The live region.
`viewport`	The scrolling container.

CSS custom properties

Property	Description
`--bmx-carousel-control-background`	Their fill.
`--bmx-carousel-control-border`	Their outline.
`--bmx-carousel-control-color`	Their glyph.
`--bmx-carousel-control-size`	The diameter of the previous and next controls.
`--bmx-carousel-dot-color`	A dot that is not current.
`--bmx-carousel-dot-current-color`	The current one.
`--bmx-carousel-dot-gap`	The space between dots.
`--bmx-carousel-dot-size`	The diameter of one dot.
`--bmx-carousel-focus-ring`	The focus indicator.
`--bmx-carousel-gap`	The space between slides.
`--bmx-carousel-per-view`	How many slides fit across. Set from the `per-view` property.
`--bmx-carousel-radius`	The corner radius of the viewport.
`--bmx-carousel-tab-padding`	The room inside a tab, in `tabs` mode.

`<bmx-checkbox>`

Properties

Property	Attribute	Type	Default	Description
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the box once it has rendered.
`checked`	`checked`	`boolean`	`false`	Whether the box is ticked. Two-way: the component writes back to it.
`description`	`description`	`string`	—	Help text below the row.
`disabled`	`disabled`	`boolean`	`false`	Disable the box.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer - a server response, typically.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container, pushing the caption away from the box.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the caption visually while keeping it as the accessible name.
`indeterminate`	`indeterminate`	`boolean`	`false`	The mixed state. Visual and semantic only - `aria-checked="mixed"` and a dash in place of the tick. It never submits, and any user interaction clears it.
`label`	`label`	`string`	—	The caption. Required unless the `label` slot is used.
`labelPlacement`	`label-placement`	`BmxCheckboxLabelPlacement`	`'end'`	Which side of the box the caption sits on. Logical, so RTL flips it.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`required`	`required`	`boolean`	`false`	Require the box to be ticked before its form will submit.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment of the box. `pill` and `circle` both round it fully.
`size`	`size`	`BmxSize`	`'md'`	Size step. Scales the box, the caption and the supporting text together.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role for the ticked state and the focus ring.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`value`	`value`	`string`	`'on'`	What the form receives when the box is ticked. Matches the native default.

Events

Event	Detail	Description
`bmxBlur`	`void`	Fired when the box loses focus.
`bmxChange`	`BmxCheckboxChangeDetail`	Fired when the ticked state changes, by user action or by `toggle()`.
`bmxFocus`	`void`	Fired when the box gains focus.
`bmxValidityChange`	`BmxCheckboxValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the box passed, without revealing anything.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the box.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the box if it has one.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the box.
`toggle`	`toggle() => Promise<void>`	Move to the next state, as a click would. Including from indeterminate, which resolves to ticked. Does nothing while the box is disabled, so a consumer's "toggle all" cannot quietly change a value the user has been told they may not change.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich caption content, in place of the `label` property.

CSS shadow parts

Part	Description
`base`	The row holding the box and its caption.
`box`	The wrapper around the control and the drawn mark.
`control`	The native checkbox.
`description`	The help text.
`error`	The error message.
`label`	The caption.
`mark`	The drawn box and tick.

CSS custom properties

Property	Description
`--bmx-checkbox-background`	The box's background when unticked.
`--bmx-checkbox-border-color`	The box's border colour when unticked.
`--bmx-checkbox-border-width`	Border width of the box in its unticked state.
`--bmx-checkbox-checked-background`	The box's background when ticked or mixed. Defaults to the tone's solid colour.
`--bmx-checkbox-duration`	How long the tick takes to draw. Zero under reduced motion.
`--bmx-checkbox-font-size`	The caption's font size.
`--bmx-checkbox-gap`	Space between the box and its caption.
`--bmx-checkbox-mark-color`	The tick and dash colour.
`--bmx-checkbox-radius`	Corner radius of the box.
`--bmx-checkbox-size`	The drawn box's width and height. The clickable target stays at least 24px regardless.
`--bmx-checkbox-support-font-size`	Font size of the description and error message.

`<bmx-chip>`

Properties

Property	Attribute	Type	Default	Description
`disabled`	`disabled`	`boolean`	`false`	Whether the chip is inert. A disabled chip keeps its place in the row and takes no focus.
`href`	`href`	`string`	—	Turns the chip into a link.
`label`	`label`	`string`	—	The chip's text, when it is not being slotted in. Useful from a template that builds chips from data, and it is what the remove button's accessible name is composed from.
`rel`	`rel`	`string`	—	The link's `rel`. Left to the consumer rather than forced: `noopener` is right for almost every `target="_blank"` and a component that adds it silently is a component that has decided something on the consumer's behalf.
`removable`	`removable`	`boolean`	`false`	Whether the chip offers a remove button.
`removeLabel`	`remove-label`	`string`	—	The remove button's accessible name. Composed from the chip's text by default - "Remove Ada Lovelace" - because a row of eight buttons all called "Remove" tells a screen-reader user which action they are on and nothing about which of the eight.
`rovingTabindex`	`roving-tabindex`	`number`	`0`	The tabindex of the chip's focusable element. Set by a parent that implements a roving tabindex - `bmx-chip-set` does - and not normally set by hand. It exists as a property because the element that really takes the focus is inside this component's shadow root, where a `tabindex` on the host cannot reach it.
`selectable`	`selectable`	`boolean`	`false`	Whether the chip can be turned on and off.
`selected`	`selected`	`boolean`	`false`	Whether it is currently on.
`target`	`target`	`string`	—	The link's target, when `href` is set.
`value`	`value`	`string`	—	What this chip stands for, reported on both of its events.

Events

Event	Detail	Description
`bmxChange`	`BmxChipChangeDetail`	The chip was turned on or off.
`bmxRemove`	`BmxChipRemoveDetail`	The remove button was pressed. A request, not a notification: the chip does not take itself out of the document, because the list it belongs to is the consumer's data and a component that deleted from it would be guessing. Cancelable, so a confirmation can stop it - `bmx-chip-set`, which does own its data, honours the cancellation.

Methods

Method	Signature	Description
`isFocusable`	`isFocusable() => Promise<boolean>`	Whether anything in this chip can take the focus.
`setFocus`	`setFocus() => Promise<void>`	Focus the chip. Whatever the chip's focusable element happens to be - the body when it is a toggle or a link, the remove button when it is not. Every focusable control in this library exposes this, and a parent looking for one tests for the method rather than for a tag name: a `bmx-chip` is not a `button`.

Slots

Slot	Description
`(default)`	The chip's text.
`start`	An avatar or an icon, before the text.

CSS shadow parts

Part	Description
`chip`	The chip's body: the span, button or anchor.
`label`	The text.
`remove`	The remove button.
`remove-icon`	The cross inside it.

CSS custom properties

Property	Description
`--bmx-chip-background`	The fill when the chip is off.
`--bmx-chip-border`	The chip's outline.
`--bmx-chip-color`	The text colour when the chip is off.
`--bmx-chip-disabled-opacity`	How faint a disabled chip is.
`--bmx-chip-focus-ring`	The focus indicator.
`--bmx-chip-font-size`	The text.
`--bmx-chip-font-weight`	How heavy it is.
`--bmx-chip-gap`	The space between an avatar, the text and the cross.
`--bmx-chip-height`	The chip's height.
`--bmx-chip-hover-background`	The fill under the pointer, on an interactive chip.
`--bmx-chip-padding-inline`	The room either side of the text.
`--bmx-chip-radius`	The corner radius. A pill by default.
`--bmx-chip-remove-color`	The cross.
`--bmx-chip-remove-hover-background`	The disc behind the cross under the pointer.
`--bmx-chip-remove-size`	The cross's hit area.
`--bmx-chip-selected-background`	The fill when the chip is on.
`--bmx-chip-selected-border`	The outline when it is on.
`--bmx-chip-selected-color`	The text colour when it is on.

`<bmx-chip-set>`

Properties

Property	Attribute	Type	Default	Description
`expandable`	`expandable`	`boolean`	`true`	Whether pressing the counter shows the rest.
`items`	property only	`BmxChipEntry[]`	`[]`	The chips, as data. Read through `src/core/markup.ts`, so `items='[{"label":"Open"}]'` written as an attribute by a Razor page, a Blazor component or an htmx swap is the list it looks like rather than a string the component tries to map over.
`label`	`label`	`string`	—	What the group is called. A row of chips with no name is announced as a group of buttons with no indication of what they filter. It is the one property here worth calling near-mandatory.
`max`	`max`	`number`	—	The most chips to draw before the rest collapse into a counter. A limit that would hide exactly one chip hides none: the counter takes the same room and says less. See `src/core/collection.ts`.
`moreLabel`	`more-label`	`string`	—	The counter's accessible name, when the composed one is not wanted.
`orientation`	`orientation`	`BmxOrientation`	`'horizontal'`	Which arrow keys move between chips.
`removable`	`removable`	`boolean`	`false`	Whether chips drawn from `items` offer a remove button.
`selectable`	`selectable`	`boolean`	`false`	Whether chips drawn from `items` can be turned on and off.
`wrap`	`wrap`	`boolean`	`true`	Whether the row wraps onto a second line rather than scrolling.

Events

Event	Detail	Description
`bmxChange`	`BmxChipSetChangeDetail`	The selection changed. Carries the whole selection, not just the chip that moved.
`bmxRemove`	`BmxChipSetRemoveDetail`	A chip drawn from `items` asked to be removed. Cancelable. Uncancelled, the set takes the entry out of `items` itself and moves the focus; prevented, nothing happens and the focus stays where it was. Chips the consumer slotted in emit their own `bmxRemove` and this one is not raised for them - the event already reached whoever wrote the chip.

Methods

Method	Signature	Description
`setFocus`	`setFocus() => Promise<void>`	Focus the set's active chip, or the set itself when it is empty.

Slots

Slot	Description
`(default)`	`bmx-chip` elements.

CSS shadow parts

Part	Description
`more`	The counter chip.
`set`	The row.

CSS custom properties

Property	Description
`--bmx-chip-set-focus-ring`	The indicator on the set itself, which is focusable only when empty.
`--bmx-chip-set-gap`	The space between chips.
`--bmx-chip-set-row-gap`	The space between rows, when the set wraps.

`<bmx-combobox>`

Properties

Property	Attribute	Type	Default	Description
`allowCustom`	`allow-custom`	`boolean`	`false`	Whether a value the user typed but did not choose is allowed. Off by default, which is the "searchable select": type to find, leave with something from the list. On, the typed text becomes the value - which is what makes this a tag input when combined with `multiple`.
`appearance`	`appearance`	`BmxComboboxAppearance`	`'outline'`	Visual treatment.
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the field once it has rendered.
`clearable`	`clearable`	`boolean`	`false`	Show a clear button once something is chosen.
`description`	`description`	`string`	—	Help text below the field.
`disabled`	`disabled`	`boolean`	`false`	Disable the field.
`emptyText`	`empty-text`	`string`	`'No matches'`	What the list says when nothing matches.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer - a server response, typically.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it as the accessible name.
`label`	`label`	`string`	—	The field's label. Required unless the `label` slot is used.
`loading`	`loading`	`boolean`	`false`	Show a busy state while a consumer fetches results.
`loadingText`	`loading-text`	`string`	`'Searching…'`	What the list says while `loading` is set.
`matcher`	property only	`BmxOptionMatcher`	—	A consumer's own matcher, in place of the default.
`maxTags`	`max-tags`	`number`	`3`	How many tags to show before the rest collapse into a count.
`maxVisibleRows`	`max-visible-rows`	`number`	`8`	How many rows the open list shows before it scrolls.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`multiple`	`multiple`	`boolean`	`false`	Allow more than one choice, shown as tags.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`options`	property only	`BmxListboxOption[]`	`[]`	The options. A property, because it is an array. Accepts the JSON spelling of the list as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`placeholder`	`placeholder`	`string`	`'Type to search…'`	Placeholder text. Never a substitute for a label.
`placement`	`placement`	`BmxPlacement`	`'bottom-start'`	Which side the list opens on when there is room.
`readonly`	`readonly`	`boolean`	`false`	Make the field read-only. It still submits and is still focusable.
`required`	`required`	`boolean`	`false`	Require a choice before the form will submit.
`serverFilter`	`server-filter`	`boolean`	`false`	Filter elsewhere. See the note on the class.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment. `circle` is not meaningful here and behaves as `pill`.
`showChevron`	`show-chevron`	`boolean`	`true`	Show the disclosure arrow, which opens the unfiltered list.
`size`	`size`	`BmxSize`	`'md'`	Size step.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role, used for the focus ring and the chosen option.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`value`	`value`	`string \| null`	`null`	The chosen value in single mode. Two-way.
`values`	property only	`string[]`	`[]`	The chosen values in `multiple` mode. Two-way. Accepts a comma-separated or JSON string as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`virtualThreshold`	`virtual-threshold`	`number`	`100`	The row count above which the list is windowed.

Events

Event	Detail	Description
`bmxBlur`	`void`	Fired when the field loses focus.
`bmxChange`	`BmxComboboxChangeDetail`	Fired when the selection changes.
`bmxFilter`	`BmxComboboxFilterDetail`	Fired on every edit, with what the user has typed.
`bmxFocus`	`void`	Fired when the field gains focus.
`bmxOpenChange`	`boolean`	Fired when the list opens or closes.
`bmxValidityChange`	`BmxComboboxValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the field passed, without revealing anything.
`clear`	`clear() => Promise<void>`	Empty the selection and the text.
`closeList`	`closeList() => Promise<void>`	Close the list without committing.
`getQuery`	`getQuery() => Promise<string>`	What the user has typed.
`getSelectedOptions`	`getSelectedOptions() => Promise<BmxListboxOption[]>`	The options behind the current selection.
`openList`	`openList() => Promise<void>`	Open the list, unfiltered.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the field.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the field if it has one.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the field.

Slots

Slot	Description
`(default)`	`bmx-option` elements, when options are written rather than passed.
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.

CSS shadow parts

Part	Description
`chevron`	The disclosure arrow.
`clear`	The clear button.
`control`	The text input carrying `role="combobox"`.
`description`	The help text.
`empty`	The message shown when nothing matches.
`error`	The error message.
`field`	The bordered box.
`group`	A group heading.
`label`	The label element.
`listbox`	The floating surface.
`option`	One option row.
`tag`	One chosen value in `multiple` mode.
`tag-remove`	A tag's remove button.

CSS custom properties

Property	Description
`--bmx-combobox-background`	The field's background. Set by `appearance`.
`--bmx-combobox-border-color`	The field's border colour at rest.
`--bmx-combobox-border-width`	Border width of the field.
`--bmx-combobox-font-size`	The text's font size.
`--bmx-combobox-gap`	Space between the tags, the input and the chevron.
`--bmx-combobox-group-height`	A group heading's height.
`--bmx-combobox-height`	The field's height.
`--bmx-combobox-label-font-size`	The label's font size.
`--bmx-combobox-list-background`	The floating list's background.
`--bmx-combobox-list-shadow`	The list's shadow.
`--bmx-combobox-option-active-background`	The background of the option the keyboard is on.
`--bmx-combobox-option-height`	A row's height in the open list.
`--bmx-combobox-option-selected-background`	The chosen option's background.
`--bmx-combobox-padding-inline`	Horizontal padding inside the field.
`--bmx-combobox-placeholder-color`	Placeholder colour. Dimmer than a value, and still AA against the field.
`--bmx-combobox-radius`	Corner radius of the field and the list.
`--bmx-combobox-stack-gap`	Space between the label, the field and the supporting text.
`--bmx-combobox-support-font-size`	Font size of the description and error message.

`<bmx-date-picker>`

Properties

Property	Attribute	Type	Default	Description
`appearance`	`appearance`	`BmxDatePickerAppearance`	`'outline'`	Visual treatment.
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the field once it has rendered.
`description`	`description`	`string`	—	Help text below the field.
`disabled`	`disabled`	`boolean`	`false`	Disable the field.
`disabledDates`	`disabled-dates`	`string[] \| string`	`[]`	Individual dates that cannot be chosen, as `YYYY-MM-DD`. Accepts a comma-separated or JSON string as well - a bank-holiday list written by a server-side template is the case this exists for. See the note on `disabledDaysOfWeek` for why the type says `\| string`.
`disabledDaysOfWeek`	`disabled-days-of-week`	`number[] \| string`	`[]`	Days of the week that can never be chosen. Sunday is 0. Accepts a comma-separated or JSON string as well. The `\| string` in the type is not decoration: without it Stencil observes this prop under its own camelCase name, which the HTML parser lowercases, so `disabled-days-of-week` would not exist as an attribute at all. See `src/core/markup.ts`.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer.
`firstDayOfWeek`	`first-day-of-week`	`number`	—	Override the first day of the week. Sunday is 0.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it as the accessible name.
`isDateUnavailable`	property only	`(iso: string) => boolean`	—	A consumer's own rule, asked after the others.
`label`	`label`	`string`	—	The field's label. Required unless the `label` slot is used.
`locale`	`locale`	`string`	—	The locale to write dates in. Defaults to the document's.
`max`	`max`	`string`	—	The latest date that may be chosen, as `YYYY-MM-DD`.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`min`	`min`	`string`	—	The earliest date that may be chosen, as `YYYY-MM-DD`.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`placement`	`placement`	`BmxPlacement`	`'bottom-start'`	Which side the calendar opens on when there is room.
`presets`	property only	`BmxDatePreset[]`	`[]`	Named shortcuts, shown beside the calendar. Accepts the JSON spelling of the list as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`range`	`range`	`boolean`	`false`	Choose two dates rather than one.
`readonly`	`readonly`	`boolean`	`false`	Make the field read-only. It still submits and is still focusable.
`required`	`required`	`boolean`	`false`	Require a date before the form will submit.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment.
`size`	`size`	`BmxSize`	`'md'`	Size step.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`value`	`value`	`string \| null`	`null`	The chosen date as `YYYY-MM-DD`. Two-way: the component writes back to it.
`values`	property only	`string[]`	`[]`	Both ends in `range` mode, as `YYYY-MM-DD`. Two-way. Accepts a comma-separated or JSON string as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`withTime`	`with-time`	`boolean`	`false`	Add a time field under the calendar. The value becomes `YYYY-MM-DDTHH:mm`.

Events

Event	Detail	Description
`bmxChange`	`BmxDatePickerChangeDetail`	Fired when the chosen date changes.
`bmxOpenChange`	`boolean`	Fired when the calendar opens or closes.
`bmxValidityChange`	`BmxDatePickerValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the field passed, without revealing anything.
`clear`	`clear() => Promise<void>`	Empty the selection.
`closeCalendar`	`closeCalendar() => Promise<void>`	Close the calendar.
`openCalendar`	`openCalendar() => Promise<void>`	Open the calendar.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the field.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the field if it has one.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the field.

Slots

Slot	Description
`(default)`	The default slot
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.

CSS shadow parts

Part	Description
`calendar`	The floating surface.
`control`	The text input carrying `role="combobox"`.
`day`	One day cell.
`description`	The help text.
`error`	The error message.
`field`	The bordered box.
`grid`	The `role="grid"` of days.
`header`	The month name and the paging buttons.
`label`	The label element.
`preset`	One named shortcut.
`time`	The time field, with `with-time`.
`trigger`	The button that opens the calendar.

CSS custom properties

Property	Description
`--bmx-date-background`	The field's background. Set by `appearance`.
`--bmx-date-border-color`	The field's border colour at rest.
`--bmx-date-border-width`	Border width of the field.
`--bmx-date-calendar-background`	The floating calendar's background.
`--bmx-date-calendar-shadow`	The calendar's shadow.
`--bmx-date-cell-radius`	Corner radius of a day.
`--bmx-date-cell-size`	The width and height of one day.
`--bmx-date-font-size`	The typed date's font size.
`--bmx-date-height`	The field's height.
`--bmx-date-label-font-size`	The label's font size.
`--bmx-date-padding-inline`	Horizontal padding inside the field.
`--bmx-date-radius`	Corner radius of the field and the calendar.
`--bmx-date-range-background`	The days between the two ends of a range.
`--bmx-date-selected-background`	A chosen day. Defaults to the tone's solid colour.
`--bmx-date-support-font-size`	Font size of the description and error message.
`--bmx-date-today-color`	The marker under today's date.

`<bmx-dialog>`

Properties

Property	Attribute	Type	Default	Description
`closeLabel`	`close-label`	`string`	`'Close'`	The close button's accessible name.
`closeOnBackdrop`	`close-on-backdrop`	`boolean`	`true`	Whether a press on the scrim dismisses it.
`closeOnEscape`	`close-on-escape`	`boolean`	`true`	Whether Escape dismisses it.
`dismissible`	`dismissible`	`boolean`	`true`	Whether the user may dismiss it. False removes the close button and refuses both Escape and the backdrop - for a dialog that must be answered rather than escaped. It does not restrain the application: `closeDialog()` always works, and a modal that survived its own submit button would be a support call.
`heading`	`heading`	`string`	—	The visible title. Also the dialog's accessible name.
`hideClose`	`hide-close`	`boolean`	`false`	Hide the close button while still allowing Escape and the backdrop.
`initialFocus`	`initial-focus`	`string \| HTMLElement`	—	What is focused when it opens, as a CSS selector or an element. Left alone, focus goes to the panel, so the dialog is announced from its name and its content rather than from whichever control happens to be first. Name something here when a particular field is obviously the point of the dialog - and note that an `autofocus` attribute on your own content wins over both, because that attribute is exactly what it is for.
`label`	`label`	`string`	—	The accessible name, for a design with no visible title.
`open`	`open`	`boolean`	`false`	Whether the dialog is showing. Mutable, so the component can close itself when the user dismisses it. A consumer driving it may treat it as controlled and watch `bmxOpenChange`.
`returnFocus`	`return-focus`	`boolean`	`true`	Whether closing returns focus to whatever opened it.
`size`	`size`	`BmxDialogSize`	`'md'`	The panel's width step. `full` fills the viewport.

Events

Event	Detail	Description
`bmxClose`	`BmxDialogCloseDetail`	Fired once it has finished closing, with why it closed.
`bmxOpenChange`	`boolean`	Fired when the dialog opens or closes.

Methods

Method	Signature	Description
`closeDialog`	`closeDialog() => Promise<void>`	Close the dialog. Always permitted, whatever `dismissible` says - that property restrains the user, not the application.
`openDialog`	`openDialog() => Promise<void>`	Open the dialog.

Slots

Slot	Description
`(default)`	The dialog's content.
`footer`	The row of actions along the bottom.
`heading`	Replaces the plain-text `heading`.

CSS shadow parts

Part	Description
`body`	The scrolling content area.
`close`	The close button.
`dialog`	The native element, which is also the scrim.
`footer`	The row of actions.
`header`	The bar across the top.
`heading`	The title within it.
`panel`	The box the content sits in.

CSS custom properties

Property	Description
`--bmx-dialog-inset`	Space kept between the panel and the viewport's edges.
`--bmx-dialog-padding`	Space inside the panel's header, body and footer.
`--bmx-dialog-radius`	Corner radius of the panel.
`--bmx-dialog-scrim`	The colour laid over the page behind it.
`--bmx-dialog-width`	The panel's width at the current size step.

`<bmx-drawer>`

Properties

Property	Attribute	Type	Default	Description
`closeLabel`	`close-label`	`string`	`'Close'`	The close button's accessible name.
`closeOnBackdrop`	`close-on-backdrop`	`boolean`	`true`	Whether a press on the scrim dismisses it.
`closeOnEscape`	`close-on-escape`	`boolean`	`true`	Whether Escape dismisses it.
`dismissible`	`dismissible`	`boolean`	`true`	Whether the user may dismiss it. Never restrains `closeDrawer()`.
`edge`	`edge`	`BmxDrawerEdge`	`'end'`	Which edge it slides in from. `start` and `end` mirror under RTL.
`heading`	`heading`	`string`	—	The visible title. Also the drawer's accessible name.
`hideClose`	`hide-close`	`boolean`	`false`	Hide the close button while still allowing Escape and the backdrop.
`initialFocus`	`initial-focus`	`string \| HTMLElement`	—	What is focused when it opens, as a CSS selector or an element.
`label`	`label`	`string`	—	The accessible name, for a design with no visible title.
`open`	`open`	`boolean`	`false`	Whether the drawer is showing. Mutable, so it can close itself.
`returnFocus`	`return-focus`	`boolean`	`true`	Whether closing returns focus to whatever opened it.
`size`	`size`	`BmxDialogSize`	`'md'`	How much of the screen it takes. The panel's width on `start` and `end`, its height on `top` and `bottom`. `full` covers the viewport, which is what a navigation drawer on a phone usually wants.

Events

Event	Detail	Description
`bmxClose`	`BmxDialogCloseDetail`	Fired once it has finished closing, with why it closed.
`bmxOpenChange`	`boolean`	Fired when the drawer opens or closes.

Methods

Method	Signature	Description
`closeDrawer`	`closeDrawer() => Promise<void>`	Close the drawer. Always permitted, whatever `dismissible` says.
`openDrawer`	`openDrawer() => Promise<void>`	Open the drawer.

Slots

Slot	Description
`(default)`	The drawer's content.
`footer`	The row of actions along the bottom.
`heading`	Replaces the plain-text `heading`.

CSS shadow parts

Part	Description
`body`	The scrolling content area.
`close`	The close button.
`dialog`	The native element, which is also the scrim.
`footer`	The row of actions.
`header`	The bar across the top.
`heading`	The title within it.
`panel`	The box the content sits in.

CSS custom properties

Property	Description
`--bmx-dialog-padding`	Space inside the panel's header, body and footer.
`--bmx-dialog-scrim`	The colour laid over the page behind it.
`--bmx-drawer-size`	The panel's width on a side edge, its height on a top or bottom one.

`<bmx-input>`

Properties

Property	Attribute	Type	Default	Description
`appearance`	`appearance`	`BmxInputAppearance`	`'outline'`	Visual treatment.
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the field once it has rendered.
`autocomplete`	`autocomplete`	`string`	—	Autocomplete hint. Worth setting: it is what makes a form fillable.
`clearable`	`clearable`	`boolean`	`false`	Show a clear button once the field has content.
`counter`	`counter`	`boolean`	`false`	Show a character counter. Pairs with `maxLength`.
`description`	`description`	`string`	—	Help text below the field. Always visible, unlike a placeholder.
`disabled`	`disabled`	`boolean`	`false`	Disable the field.
`enterkeyhint`	`enterkeyhint`	`'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'`	—	What the on-screen keyboard's action key should say.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer - a server response, typically.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it for assistive technology. For a field whose purpose is obvious from context - a search box beside a search button. Not a licence to drop labels: the accessible name still has to exist, which is why this hides rather than removes.
`inputmode`	`inputmode`	`'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url'`	—	On-screen keyboard hint.
`label`	`label`	`string`	—	The field's label. Required unless the `label` slot is used.
`mask`	`mask`	`string`	—	A mask pattern. `#` accepts a digit, `A` a letter, `*` either; every other character is a literal the mask supplies. Prefix a token with a backslash to use it as a literal. `##/##/####`, `+44 #### ######`, `\####` for a hash and three digits.
`maskEager`	`mask-eager`	`boolean`	`true`	Show the mask's separators as the user reaches them. On by default, so typing the second digit of a date shows `12/`. Turn it off for a field whose partially-filled value is stored rather than only displayed.
`maskFormat`	property only	`(raw: string) => string`	—	Render the raw value for display, in place of a pattern. For anything whose separators move as the value grows - currency, a locale-aware number. It may insert and remove characters freely but must not transform them: `1234` may become `£1,234.00`, and must not become `ONE THOUSAND`. A transforming formatter still produces the right text, but the caret can then only be placed at the end of it.
`maskParse`	property only	`(display: string) => string`	—	The inverse of `maskFormat`.
`max`	`max`	`string \| number`	—	Maximum, for the numeric and date types.
`maxLength`	`max-length`	`number`	—	Maximum length, in characters rather than UTF-16 code units. Enforced here rather than by the native attribute - see the note on the class. Also drives the counter's limit when `counter` is set.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`min`	`min`	`string \| number`	—	Minimum, for the numeric and date types.
`minLength`	`min-length`	`number`	—	Minimum length. Counted against `rawValue` when the field is masked.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`passwordToggle`	`password-toggle`	`boolean`	`false`	Show a button that reveals the password. Only for `type="password"`.
`pattern`	`pattern`	`string`	—	A regular expression the value must match, as the native attribute takes it.
`placeholder`	`placeholder`	`string`	—	Placeholder text. Never a substitute for a label.
`readonly`	`readonly`	`boolean`	`false`	Make the field read-only. It still submits and is still focusable.
`required`	`required`	`boolean`	`false`	Require a value.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment. `circle` is not meaningful here and behaves as `pill`.
`size`	`size`	`BmxSize`	`'md'`	Size step.
`spellcheck`	`spellcheck`	`boolean`	`false`	Spellchecking. Off by default for the identifiers most fields hold.
`step`	`step`	`string \| number`	—	Granularity, for the numeric and date types.
`submitValue`	`submit-value`	`BmxInputSubmitValue`	`'raw'`	Which value the form receives. See the note on the class.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role, used for the focus ring. An error overrides it.
`type`	`type`	`BmxInputType`	`'text'`	The input type.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`validator`	property only	`BmxInputValidator`	—	A consumer's own check, run once the value is structurally whole.
`value`	`value`	`string`	`''`	What the field displays, mask and all. Assigning to it runs the mask, so setting `01011990` on a date-masked field leaves `01/01/1990` behind. Read `rawValue` for the significant characters.

Events

Event	Detail	Description
`bmxBlur`	`void`	Fired when the field loses focus.
`bmxChange`	`BmxInputChangeDetail`	Fired when the field is committed - on blur, or on Enter.
`bmxClear`	`void`	Fired when the clear button is used, or `clear()` is called.
`bmxFocus`	`void`	Fired when the field gains focus.
`bmxInput`	`BmxInputChangeDetail`	Fired on every edit.
`bmxValidityChange`	`BmxInputValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the field passed. Silent: it does not reveal a message the user has not earned yet. Use `reportValidity` to both check and show.
`clear`	`clear() => Promise<void>`	Empty the field.
`getRawValue`	`getRawValue() => Promise<string>`	The significant characters, with the mask's literals removed.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the field.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the field if it has one.
`selectAll`	`selectAll() => Promise<void>`	Select the field's contents.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the field.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.
`prefix`	Content inside the field, before the input. An icon or a unit.
`suffix`	Content inside the field, after the input.

CSS shadow parts

Part	Description
`clear`	The clear button.
`control`	The native input.
`counter`	The character counter.
`description`	The help text.
`error`	The error message.
`field`	The bordered box holding the prefix, input and suffix.
`label`	The label element.
`prefix`	The leading slot wrapper.
`spinner`
`suffix`	The trailing slot wrapper.
`toggle`	The password visibility toggle.

CSS custom properties

Property	Description
`--bmx-input-background`	The field's background. Set by `appearance`; override for a one-off.
`--bmx-input-border-color`	The field's border colour in its resting state.
`--bmx-input-border-width`	Border width of the field.
`--bmx-input-font-size`	The value's font size.
`--bmx-input-gap`	Space between the prefix, the input and the suffix.
`--bmx-input-height`	The control's height. Defaults to the size step's height times the density scale.
`--bmx-input-icon-size`	Size of a slotted prefix or suffix icon, and of the clear and reveal buttons.
`--bmx-input-label-font-size`	The label's font size.
`--bmx-input-padding-inline`	Horizontal padding inside the field.
`--bmx-input-placeholder-color`	Placeholder colour. Deliberately dimmer than the value, and still AA against the field.
`--bmx-input-radius`	Corner radius of the field.
`--bmx-input-stack-gap`	Space between the label, the field and the supporting text.
`--bmx-input-support-font-size`	Font size of the description, error and counter.

`<bmx-menu>`

Properties

Property	Attribute	Type	Default	Description
`anchor`	`anchor`	`string \| HTMLElement`	—	What the root surface is placed against. Defaults to the trigger. Separate from `trigger` because the two answer different questions. A `bmx-split-button` wires the ARIA to its chevron half and anchors the menu to both halves, so that `bottom-start` lines up with the primary action's leading edge rather than hanging a wide menu off a narrow button.
`context`	`context`	`string \| HTMLElement`	—	Right-clicking inside this element opens the menu at the pointer.
`items`	property only	`BmxMenuEntry[]`	`[]`	The menu's entries. An array, or the JSON spelling of one. Anything with a wrapper - React, Angular, Vue - assigns the array; markup that can only write attributes (Razor, Blazor's markup, a server-side template, an htmx swap) writes the JSON, and it is read once into the list it describes. Mutable for that reason alone: everything below reads a list.
`label`	`label`	`string`	`'Menu'`	The menu's accessible name.
`menuId`	`menu-id`	`string`	—	The id given to the root surface. Only needed by a component that owns its own trigger and has to point that trigger's `aria-controls` at a surface it does not render itself. Left alone, the menu generates one.
`open`	`open`	`boolean`	`false`	Whether the menu is showing. Mutable, so the component can close itself when something is chosen. A consumer driving it may treat it as controlled and watch `bmxOpenChange`.
`placement`	`placement`	`BmxPlacement`	`'bottom-start'`	Which side the root opens on when there is room.
`returnFocus`	`return-focus`	`boolean`	`true`	Whether closing returns focus to whatever opened the menu.
`returnFocusTo`	`return-focus-to`	`string \| HTMLElement`	—	Where focus goes when the menu closes, as a CSS selector or an element. Defaults to the trigger, and failing that the anchor - which is right for every menu that opens itself. It is the composition case that needs this: `bmx-split-button` anchors the menu to both of its halves so the list lines up with the primary action's leading edge, but focus belongs on the chevron the user actually pressed. A selector is resolved against the menu's own root, so a composing component can name something inside its own shadow tree without waiting for a ref to exist.
`trigger`	`trigger`	`string \| HTMLElement`	—	The element that opens this menu, as a CSS selector or an element. Given one, the menu takes over its ARIA and its keyboard entirely. Omit it when the composing component already owns a trigger of its own.

Events

Event	Detail	Description
`bmxOpenChange`	`boolean`	Fired when the menu opens or closes.
`bmxSelect`	`BmxMenuSelectDetail`	Fired when an item is chosen.

Methods

Method	Signature	Description
`closeMenu`	`closeMenu() => Promise<void>`	Close the menu. Focus returns to whatever opened it.
`openAt`	`openAt(x: number, y: number) => Promise<void>`	Open the menu at a point in the viewport, as a context menu.
`openMenu`	`openMenu(atEnd?: boolean) => Promise<void>`	Open the menu against its anchor and move focus into it.

Slots

Slot	Description
`(default)`	The default slot

CSS shadow parts

Part	Description
`item`	A menu item.
`menu`	The root surface.
`separator`	A divider between items.
`submenu`	A cascaded surface. Also matches `menu` for styling.

CSS custom properties

Property	Description
`--bmx-menu-item-padding`	Space inside an item.
`--bmx-menu-max-height`	Tallest a surface grows before it scrolls.
`--bmx-menu-max-width`	Largest width a surface takes before its labels wrap.
`--bmx-menu-min-width`	Smallest width a surface takes. Default 12rem.
`--bmx-menu-padding`	Space between a surface's edge and its items.
`--bmx-menu-radius`	Corner radius of a surface.

`<bmx-menu-item>`

Properties

Property	Attribute	Type	Default	Description
`checked`	`checked`	`boolean`	`false`	The state of a `checkbox` or `radio` item.
`danger`	`danger`	`boolean`	`false`	Paint it in the danger tone.
`description`	`description`	`string`	—	Secondary text, under the label.
`disabled`	`disabled`	`boolean`	`false`	Whether it can be chosen.
`group`	`group`	`string`	—	Which radio set this belongs to. Radio items sharing one are exclusive.
`kind`	`kind`	`'action' \| 'checkbox' \| 'radio'`	`'action'`	What kind of control this is: an action, or something that carries a state.
`label`	`label`	`string`	—	What the user reads. Falls back to the element's own text.
`separator`	`separator`	`boolean`	`false`	Draw a divider instead of an item. Every other property is ignored.
`shortcut`	`shortcut`	`string`	—	A keyboard hint, right-aligned. Display only - the menu does not bind it.
`value`	`value`	`string`	—	Reported in the menu's selection event. Falls back to the label.

Slots

Slot	Description
`(default)`	The item's label, when the `label` property is not set. Nested `bmx-menu-item` elements here become the item's submenu.

`<bmx-option>`

Properties

Property	Attribute	Type	Default	Description
`description`	`description`	`string`	—	Secondary text, under the label.
`disabled`	`disabled`	`boolean`	`false`	Whether it can be chosen.
`group`	`group`	`string`	—	The heading this option sits under. A heading appears whenever this changes from one option to the next, so the document order is the display order and nothing is regrouped on the author's behalf.
`label`	`label`	`string`	—	What the user reads. Falls back to the element's own text.
`value`	`value`	`string`	—	What the form receives when this option is chosen. Must be unique in its list.

Slots

Slot	Description
`(default)`	The option's label, when the `label` property is not set.

`<bmx-org-chart>`

Properties

Property	Attribute	Type	Default	Description
`initialDepth`	`initial-depth`	`number`	—	How many generations to open on first render. A chart that opens with eleven hundred boxes on it has answered no question anybody had. Left unset, everything is open except the nodes that said `collapsed` themselves.
`label`	`label`	`string`	—	What the tree is called. Without one it is announced as "Organisation chart".
`levelGap`	`level-gap`	`number`	`56`	The gap between one generation and the next, in pixels.
`nodeHeight`	`node-height`	`number`	`72`	The least a box may be, in pixels. A floor rather than a height: the real height is measured, because a consumer's font, padding or a job title that wraps to two lines all change it and a layout that used this number regardless would draw the boxes overlapping.
`nodeWidth`	`node-width`	`number`	`176`	How wide a box is, in pixels. A layout input rather than a styling one, and the distinction matters because this library does not take `@Prop()`s for looks. The arithmetic cannot run without a number, and it cannot read one out of a custom property - `getComputedStyle` hands those back unresolved, which is §6c item 5 and cost `bmx-select` a build cycle. So the number comes in here and the component writes it into the CSS, which keeps the box that is drawn and the box that was laid out the same box by construction. Everything about how a node looks is still CSS: see the parts below.
`nodes`	`nodes`	`BmxOrgNode[] \| string`	`[]`	The people, as a flat list. Read through `src/core/markup.ts`, so `nodes='[{...}]'` written in a Razor page, a Blazor component or plain HTML works exactly as an assignment from React does - which is defect 45's whole subject.
`orientation`	`orientation`	`BmxOrgOrientation`	`'vertical'`	Which way the generations run.
`siblingGap`	`sibling-gap`	`number`	`24`	The gap between two boxes side by side, in pixels.

Events

Event	Detail	Description
`bmxSelect`	`BmxOrgChartSelectDetail`	A node was chosen - clicked, or Enter or Space on it.
`bmxToggle`	`BmxOrgChartToggleDetail`	A branch was opened or closed.

Methods

Method	Signature	Description
`collapseAll`	`collapseAll() => Promise<void>`	Close every branch that has anything in it.
`expandAll`	`expandAll() => Promise<void>`	Open every branch.
`focusNode`	`focusNode(id: string) => Promise<void>`	Put the tab stop on a node, and the focus with it.
`toggle`	`toggle(id: string, expanded?: boolean) => Promise<void>`	Open or close one branch by id.

Slots

Slot	Description
`empty`	what to draw when there are no nodes at all.

CSS shadow parts

Part	Description
`canvas`
`empty`
`node-count`
`node-detail`
`node-handle`
`node-label`
`tree`
`wire`
`wires`

CSS custom properties

Property	Description
`--bmx-org-node-background`	The box's fill.
`--bmx-org-node-border`	Its border.
`--bmx-org-node-color`	Its text.
`--bmx-org-node-height`	The least a box may be. From `node-height`.
`--bmx-org-node-radius`	Its corner radius.
`--bmx-org-node-width`	How wide a box is. Written by the component from `node-width`, so the box drawn and the box laid out are the same box.
`--bmx-org-wire-color`	The connectors.
`--bmx-org-wire-width`	How thick they are. @part canvas - the whole drawing area. @part wires - the SVG layer of connectors. @part wire - one connector. @part tree - the `role="tree"` that holds the boxes. @part node - one box. Also `node-branch` or `node-leaf`, and `node-<category>`. @part node-label - the name inside it. @part node-detail - the second line. @part node-handle - the plus or minus that opens the branch. @part node-count - the `+6` on a closed branch. @part empty - what is drawn when there is nothing to chart.

`<bmx-pagination>`

Properties

Property	Attribute	Type	Default	Description
`boundaries`	`boundaries`	`number`	`1`	How many pages to pin at each end.
`compact`	`compact`	`boolean`	`false`	Draw only the previous and next buttons, with the page as text between. What a narrow screen wants. It is a property rather than a media query because the component cannot know how much room the page has given it - a container query in the consumer's stylesheet can set it, and often should.
`disabled`	`disabled`	`boolean`	`false`	Nothing can be pressed. The current page is still readable.
`firstLabel`	`first-label`	`string`	`'First page'`	The labels on the four movement buttons, and on the size control.
`label`	`label`	`string`	`'Pagination'`	The navigation landmark's accessible name.
`lastLabel`	`last-label`	`string`	`'Last page'`
`nextLabel`	`next-label`	`string`	`'Next page'`
`page`	`page`	`number`	`1`	The page being looked at, counting from 1.
`pageSize`	`page-size`	`number`	`20`	How many rows a page holds.
`pageSizes`	`page-sizes`	`number[] \| string`	`[]`	The page sizes a reader may choose between. An empty list - the default - draws no size control at all. Given some, the control appears, and changing it keeps the row you are looking at on screen rather than the page number: at twenty per page, page 4 is rows 61 to 80, and at fifty per page those rows are on page 2. Landing on page 4 of the new pagination would show rows 151 to 200, which you have never seen. Accepts a comma-separated or JSON string as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`pages`	`pages`	`number`	—	How many pages there are. Set this when your API tells you a page count and nothing else. When `totalItems` is given, that wins - it is the more precise fact, and it is what the summary and the page-size control need.
`previousLabel`	`previous-label`	`string`	`'Previous page'`
`showEdges`	`show-edges`	`boolean`	`false`	Whether to draw the jump-to-first and jump-to-last buttons.
`showSummary`	`show-summary`	`boolean`	`false`	Whether to draw the "21-40 of 813" summary. Needs `totalItems`.
`siblings`	`siblings`	`number`	`1`	How many pages to show either side of the current one.
`sizeLabel`	`size-label`	`string`	`'Rows per page'`
`totalItems`	`total-items`	`number`	—	How many rows there are altogether.

Events

Event	Detail	Description
`bmxChange`	`BmxPaginationChangeDetail`	Fired when the reader asks for a different page, or a different page size.

Methods

Method	Signature	Description
`goTo`	`goTo(page: number) => Promise<void>`	Go to a page. Clamped, and silent if it is the page already showing.
`next`	`next() => Promise<void>`	Go forward one page, if there is one.
`previous`	`previous() => Promise<void>`	Go back one page, if there is one.

CSS shadow parts

Part	Description
`base`	The `<nav>`.
`current`	The page button for the page you are on. Carries `part="page"` as well.
`first`	The button that jumps to page one.
`gap`	An ellipsis.
`last`	The button that jumps to the final page.
`list`	The row of controls.
`next`	The button that goes forward one page.
`page`	One page button.
`previous`	The button that goes back one page.
`size`	The rows-per-page control.
`summary`	The "21-40 of 813" text.

CSS custom properties

Property	Description
`--bmx-pagination-background-hover`	A button's background under the pointer.
`--bmx-pagination-border-color`	The border on a page button.
`--bmx-pagination-color`	A page number's colour.
`--bmx-pagination-current-background`	The background behind it.
`--bmx-pagination-current-color`	The colour of the page you are on.
`--bmx-pagination-gap`	Space between one control and the next.
`--bmx-pagination-radius`	A button's corner radius.
`--bmx-pagination-size`	The height and minimum width of a page button.
`--bmx-pagination-summary-color`	The "21-40 of 813" text.

`<bmx-popover>`

Properties

Property	Attribute	Type	Default	Description
`closeLabel`	`close-label`	`string`	`'Close'`	The close button's accessible name.
`closeOnFocusLeave`	`close-on-focus-leave`	`boolean`	`true`	Whether it closes when focus leaves it. On, and it is what makes a non-modal panel behave: one that stays open behind the user's focus is a panel covering whatever they Tab to next. Turn it off for a panel that deliberately outlives the interaction - a pinned inspector - and give the user another way out.
`disabled`	`disabled`	`boolean`	`false`	Nothing opens it.
`distance`	`distance`	`number`	`8`	Gap between the trigger and the panel, in pixels.
`for`	`for`	`string \| HTMLElement`	—	What opens it: a selector, or the element itself. Left off, it is the element immediately before this one. The trigger's `aria-haspopup`, `aria-expanded` and `aria-controls` are wired for you, and a press toggles the panel - so the whole widget is one attribute and no script, exactly as `bmx-menu`'s `trigger` is.
`label`	`label`	`string`	—	The panel's accessible name. A dialog without one is announced as "dialog" and nothing else. When there is a `header` slot its text is used instead, which is usually what an author meant.
`open`	`open`	`boolean`	`false`	Whether it is open.
`placement`	`placement`	`BmxPlacement`	`'bottom-start'`	Where it prefers to sit. It flips when there is no room.
`returnFocus`	`return-focus`	`boolean`	`true`	Whether closing returns focus to the trigger.

Events

Event	Detail	Description
`bmxToggle`	`BmxPopoverToggleDetail`	Fired when it opens or closes, saying which and why.

Methods

Method	Signature	Description
`closePopover`	`closePopover() => Promise<void>`	Close it.
`openPopover`	`openPopover() => Promise<void>`	Open it. Named for the component, not for the platform's `showPopover`.

Slots

Slot	Description
`(default)`	The panel's content.
`footer`	Actions along the bottom.
`header`	A heading. Names the dialog when `label` is not given.

CSS shadow parts

Part	Description
`arrow`	The pointer drawn against the trigger.
`close`	The close button.
`content`	The body.
`footer`	The actions row.
`header`	The heading row.
`surface`	The floating panel.

CSS custom properties

Property	Description
`--bmx-popover-arrow-size`	The pointer's size. Set it to 0 for no pointer at all.
`--bmx-popover-background`	The panel's background.
`--bmx-popover-border-color`	Its border.
`--bmx-popover-color`	Its text colour.
`--bmx-popover-gap`	Space between the header, the body and the footer.
`--bmx-popover-inline-size`	How wide the panel is.
`--bmx-popover-max-block-size`	How tall it may grow before the body scrolls.
`--bmx-popover-padding`	Space inside the body.
`--bmx-popover-radius`	Its corner radius.
`--bmx-popover-shadow`	The shadow under it.

`<bmx-progress>`

Properties

Property	Attribute	Type	Default	Description
`announceEvery`	`announce-every`	`number`	`20`	How often to announce progress, in per cent. `0` never announces. Twenty is five utterances for a whole operation: enough to know it is moving, few enough to ignore. Lower it for something slow and important; set it to 0 when the same progress is already being reported somewhere else on the page, because two live regions describing one operation is worse than either alone.
`buffer`	`buffer`	`number`	—	A second, fainter value on the same track. For the two-speed cases: how much of a video has buffered against how much has played, how much of an upload has been accepted against how much has been sent. It is drawn and never announced - a screen-reader user being read two numbers for one operation learns less, not more.
`label`	`label`	`string`	—	The accessible name. Say what is progressing, not that something is.
`max`	`max`	`number`	`100`	The top of the range.
`min`	`min`	`number`	`0`	The bottom of the range.
`shape`	`shape`	`BmxProgressShape`	`'bar'`	A bar or a ring.
`showValue`	`show-value`	`boolean`	`false`	Whether to draw the value beside the bar, or inside the ring.
`size`	`size`	`BmxSize`	`'md'`	The size step.
`thickness`	`thickness`	`number`	`4`	The ring's stroke, in units of its 48-unit viewBox. A property rather than a custom property, and the one place this library bends its own rule that looks belong in CSS. The arc is drawn as a dash pattern round a circle, and both the circle's radius and the length of that dash are computed from this number - so a thickness the component could not read would be a ring whose arc ended in the wrong place, or one clipped by its own viewBox on all four sides. `getComputedStyle` cannot hand back an unregistered custom property resolved (§6c item 5), so reading it is not an option either. The ring's size is CSS, where it belongs: `--bmx-progress-ring-size`, and the viewBox scales to it.
`tone`	`tone`	`BmxTone`	`'primary'`	The semantic colour.
`value`	`value`	`number`	—	How far through it is. Leave it off for an indeterminate indicator. That is a state rather than a gap: plenty of work has no measurable end, and saying so is better than inventing a number that creeps to 90% and stops.
`valueText`	`value-text`	`string`	—	What to say instead of the percentage. "3 of 10 files" is a better thing to hear than "30%", and it is what `aria-valuetext` is for. It replaces the announcement and the drawn value both, so the two cannot disagree.

CSS shadow parts

Part	Description
`buffer`	The secondary fill, when there is a `buffer`.
`fill`	The filled part.
`ring`	The `<svg>`, in ring shape.
`ring-fill`	The arc itself.
`ring-track`	The circle behind the arc.
`track`	The groove the fill runs in, and the element carrying the role.
`value`	The percentage, when `show-value` is set.

CSS custom properties

Property	Description
`--bmx-progress-buffer`	The second, fainter fill.
`--bmx-progress-duration`	One cycle of the indeterminate animation.
`--bmx-progress-fill`	The filled part. Follows the tone by default.
`--bmx-progress-radius`	The bar's end caps. Half the thickness is a pill; 0 is square.
`--bmx-progress-ring-size`	How large the ring is drawn. Its viewBox scales to whatever this says.
`--bmx-progress-track`	The groove behind it.
`--bmx-progress-track-size`	How thick the bar is. The size step sets it; this overrides that.
`--bmx-progress-value-color`	The percentage's text colour.
`--bmx-progress-value-size`	The percentage's text size.

`<bmx-radio>`

Properties

Property	Attribute	Type	Default	Description
`checked`	`checked`	`boolean`	`false`	Whether this is the chosen option. Written by the group. Setting it by hand selects the option visually without telling the group, which is how two options end up looking chosen - set the group's `value` instead.
`disabled`	`disabled`	`boolean`	`false`	Disable this option. The group skips it when arrowing.
`label`	`label`	`string`	—	The option's caption. Use the default slot for rich content.
`rovingTabindex`	`roving-tabindex`	`number`	`-1`	This option's place in the group's single tab stop. Set by the group and not normally set by hand. Unlike `bmx-button`'s property of the same name, the focusable element here is the host, so this is rendered straight onto it - but the name is the same because the job is: a composite widget that cannot take its children out of the tab order cannot implement the WAI-ARIA keyboard pattern at all.
`size`	`size`	`BmxSize`	`'md'`	Size step. The group sets it on every option that has not set its own.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role. The group sets it on every option that has not set its own.
`value`	`value`	`string`	—	The value this option contributes when it is chosen. Required in practice: it is what the group writes into its own `value` and what the form receives. An option without one falls back to its position, which works and is not what anybody wants in a submitted payload.

Methods

Method	Signature	Description
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the option. Called by the group when the arrow keys move.

Slots

Slot	Description
`(default)`	The option's caption, in place of the `label` property.

CSS shadow parts

Part	Description
`base`	The row holding the dot and the caption.
`box`	The wrapper around the drawn dot.
`label`	The caption.
`mark`	The drawn circle and dot.

CSS custom properties

Property	Description
`--bmx-radio-accent`	The colour of the selected ring and dot. Defaults to the tone's solid colour.
`--bmx-radio-background`	The circle's background when unselected.
`--bmx-radio-border-color`	The circle's border colour when unselected.
`--bmx-radio-border-width`	Border width of the circle when unselected.
`--bmx-radio-duration`	How long the dot takes to appear. Zero under reduced motion.
`--bmx-radio-font-size`	The caption's font size.
`--bmx-radio-gap`	Space between the circle and its caption.
`--bmx-radio-size`	The drawn circle's diameter. The clickable target stays at least 24px regardless.

`<bmx-radio-group>`

Properties

Property	Attribute	Type	Default	Description
`description`	`description`	`string`	—	Help text below the options.
`disabled`	`disabled`	`boolean`	`false`	Disable every option in the group. Options may still be disabled individually.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer - a server response, typically.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the caption visually while keeping it as the accessible name.
`label`	`label`	`string`	—	The group's caption - the question the options answer. Not optional in practice: a radiogroup announced with no name tells a screen reader user only that some options have been grouped, and the options themselves rarely make sense without the question.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`orientation`	`orientation`	`BmxOrientation`	`'vertical'`	Layout direction. Both axes move the selection either way; this is visual.
`required`	`required`	`boolean`	`false`	Require an answer before the form will submit.
`size`	`size`	`BmxSize`	`'md'`	Applied to every option that has not set its own.
`tone`	`tone`	`BmxTone`	`'primary'`	Applied to every option that has not set its own.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the group is willing to reveal a problem.
`value`	`value`	`string \| null`	`null`	The chosen option's value. Two-way: the group writes back to it.
`wrapFocus`	`wrap-focus`	`boolean`	`true`	Whether arrowing past the last option returns to the first.

Events

Event	Detail	Description
`bmxChange`	`BmxRadioGroupChangeDetail`	Fired when the chosen option changes.
`bmxValidityChange`	`BmxRadioGroupValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the group passed, without revealing anything.
`refresh`	`refresh() => Promise<void>`	Re-read the options. Call after adding or removing them imperatively.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the group if it has one.
`setFocus`	`setFocus() => Promise<void>`	Move focus to the group - onto the chosen option, or the first available one.

Slots

Slot	Description
`(default)`	`bmx-radio` elements.
`description`	Rich help text, in place of the `description` property.
`label`	Rich caption content, in place of the `label` property.

CSS shadow parts

Part	Description
`base`	The element carrying `role="radiogroup"`.
`description`	The help text.
`error`	The error message.
`label`	The group's caption.

CSS custom properties

Property	Description
`--bmx-radio-group-gap`	Space between the options.
`--bmx-radio-group-label-font-size`	The question's font size.
`--bmx-radio-group-stack-gap`	Space between the question, the options and the supporting text.
`--bmx-radio-group-support-font-size`	Font size of the description and error message.

`<bmx-rating>`

Properties

Property	Attribute	Type	Default	Description
`allowHalf`	`allow-half`	`boolean`	`false`	Let the user pick halves. Doubles the answers, not the icons.
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the field once it has rendered.
`clearable`	`clearable`	`boolean`	`false`	Let the user take the rating back off. Off by default: a rating is usually being asked for rather than offered. With it on, clicking the current value again clears it, and so does arrowing back off the lowest star - which is the only way to undo a rating from the keyboard, since there is no "none of these" to arrow onto.
`description`	`description`	`string`	—	Help text below the field.
`disabled`	`disabled`	`boolean`	`false`	Disable the field.
`emptyText`	`empty-text`	`string`	`'No rating'`	What an unrated field is announced as.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer - a server response, typically.
`format`	property only	`BmxRatingFormatter`	—	Your own wording for the announcement and the caption. One function for both, so a rating cannot end up showing "Good" and announcing "4".
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it for assistive technology.
`icon`	`icon`	`BmxRatingIcon`	`'star'`	Which glyph.
`iconPath`	`icon-path`	`string`	—	Your own glyph, as a path in a 24x24 box. Overrides `icon`.
`label`	`label`	`string`	—	The field's label. Required unless the `label` slot is used.
`max`	`max`	`number`	`5`	How many icons.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`readonly`	`readonly`	`boolean`	`false`	Show the rating without letting it be changed. Renders as an image.
`required`	`required`	`boolean`	`false`	Require a rating.
`showValue`	`show-value`	`boolean`	`false`	Show the value beside the icons.
`size`	`size`	`BmxSize`	`'md'`	Size step.
`tone`	`tone`	`BmxTone`	`'warning'`	Semantic colour role. `warning` by default, alone in this library, because that is the amber a five-star rating is drawn in everywhere. A rating in the primary blue is not a rating anybody recognises, and defaulting to consistency here would cost more than it bought.
`unit`	`unit`	`string`	`'star'`	The noun in the announcement. Pluralised by adding an `s`.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`value`	`value`	`number`	`0`	The rating. Zero means no rating, which is not the same as one star.

Events

Event	Detail	Description
`bmxChange`	`BmxRatingChangeDetail`	Fired when the value is committed.
`bmxInput`	`BmxRatingChangeDetail`	Fired as the value changes during a drag.
`bmxValidityChange`	`BmxRatingValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the field passed, without revealing it.
`clear`	`clear() => Promise<void>`	Take the rating off, whatever `clearable` says.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the field.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the field if it has one.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the field.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.

CSS shadow parts

Part	Description
`description`	The help text.
`error`	The error message.
`field`	The row of icons.
`icon`	One icon.
`label`	The label element.
`value`	The value caption, when `showValue` is on.

CSS custom properties

Property	Description
`--bmx-rating-color`	The filled colour. Follows `tone` unless overridden.
`--bmx-rating-empty-color`	The unfilled colour.
`--bmx-rating-gap`	Space between icons.
`--bmx-rating-hover-color`	The filled colour while the pointer is over the row.
`--bmx-rating-label-font-size`	The label's font size.
`--bmx-rating-size`	The height and width of one icon.
`--bmx-rating-stack-gap`	Space between the label, the row and the supporting text.
`--bmx-rating-support-font-size`	Font size of the description, error and value caption.

`<bmx-select>`

Properties

Property	Attribute	Type	Default	Description
`appearance`	`appearance`	`BmxSelectAppearance`	`'outline'`	Visual treatment of the closed control.
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the control once it has rendered.
`clearable`	`clearable`	`boolean`	`false`	Show a clear button once something is chosen.
`closeOnSelect`	`close-on-select`	`boolean`	—	Close the list after a choice. Defaults to true for single, false for multiple.
`description`	`description`	`string`	—	Help text below the field.
`disabled`	`disabled`	`boolean`	`false`	Disable the control.
`emptyText`	`empty-text`	`string`	`'No options'`	What the list says when it has nothing in it.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer - a server response, typically.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it as the accessible name.
`label`	`label`	`string`	—	The field's label. Required unless the `label` slot is used.
`maxTags`	`max-tags`	`number`	`3`	How many tags to show before the rest collapse into a count. A closed control that grows to four lines because somebody chose eight things pushes the rest of the form down the page every time it is used.
`maxVisibleRows`	`max-visible-rows`	`number`	`8`	How many rows the open list shows before it scrolls.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`multiple`	`multiple`	`boolean`	`false`	Allow more than one choice. Changes what the closed control shows to tags.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`options`	property only	`BmxListboxOption[]`	`[]`	The options. A property, because it is an array. See the note on the class. Accepts the JSON spelling of the list as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`placeholder`	`placeholder`	`string`	`'Select…'`	Text shown when nothing is chosen. Never a substitute for a label.
`placement`	`placement`	`BmxPlacement`	`'bottom-start'`	Which side the list opens on when there is room.
`required`	`required`	`boolean`	`false`	Require a choice before the form will submit.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment. `circle` is not meaningful here and behaves as `pill`.
`size`	`size`	`BmxSize`	`'md'`	Size step.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role, used for the focus ring and the chosen option.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`value`	`value`	`string \| null`	`null`	The chosen value in single mode. Two-way: the component writes back to it.
`values`	property only	`string[]`	`[]`	The chosen values in `multiple` mode. Two-way. Accepts a comma-separated or JSON string as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`virtualThreshold`	`virtual-threshold`	`number`	`100`	The row count above which the list is windowed. Below it, rows are rendered in full and may be any height. Above it, the two height custom properties decide the geometry - see the note on the class. Set it to 0 to always window, or to `Infinity` never to.

Events

Event	Detail	Description
`bmxBlur`	`void`	Fired when the control loses focus.
`bmxChange`	`BmxSelectChangeDetail`	Fired when the selection changes.
`bmxFocus`	`void`	Fired when the control gains focus.
`bmxOpenChange`	`boolean`	Fired when the list opens or closes.
`bmxValidityChange`	`BmxSelectValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the field passed, without revealing anything.
`clear`	`clear() => Promise<void>`	Empty the selection.
`closeList`	`closeList() => Promise<void>`	Close the list. Focus returns to the control.
`getSelectedOptions`	`getSelectedOptions() => Promise<BmxListboxOption[]>`	The options behind the current selection, in the list's order.
`openList`	`openList() => Promise<void>`	Open the list.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the control.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the field if it has one.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the control.

Slots

Slot	Description
`(default)`	`bmx-option` elements, when options are written rather than passed.
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.

CSS shadow parts

Part	Description
`chevron`	The disclosure arrow.
`clear`	The clear button.
`control`	The trigger carrying `role="combobox"`.
`description`	The help text.
`empty`	The message shown when there are no options.
`error`	The error message.
`field`	The bordered box that is the closed control.
`group`	A group heading.
`label`	The label element.
`listbox`	The floating surface.
`option`	One option row.
`tag`	One chosen value in `multiple` mode.
`tag-remove`	A tag's remove button.
`value`	The chosen label, or the placeholder.

CSS custom properties

Property	Description
`--bmx-select-background`	The control's background. Set by `appearance`.
`--bmx-select-border-color`	The control's border colour at rest.
`--bmx-select-border-width`	Border width of the control.
`--bmx-select-font-size`	The value's font size.
`--bmx-select-gap`	Space between the value, the tags and the chevron.
`--bmx-select-group-height`	A group heading's height. Load-bearing in the same way.
`--bmx-select-height`	The closed control's height.
`--bmx-select-label-font-size`	The label's font size.
`--bmx-select-list-background`	The floating list's background.
`--bmx-select-list-shadow`	The list's shadow, which is what lifts it off the page.
`--bmx-select-option-active-background`	The background of the option the keyboard is on.
`--bmx-select-option-height`	A row's height. Load-bearing above the virtualisation threshold — see the note above.
`--bmx-select-option-selected-background`	The chosen option's background.
`--bmx-select-padding-inline`	Horizontal padding inside the control.
`--bmx-select-placeholder-color`	Placeholder colour. Dimmer than a value, and still AA against the control.
`--bmx-select-radius`	Corner radius of the control and the list.
`--bmx-select-stack-gap`	Space between the label, the control and the supporting text.
`--bmx-select-support-font-size`	Font size of the description and error message.

`<bmx-skeleton>`

Properties

Property	Attribute	Type	Default	Description
`animation`	`animation`	`'shimmer' \| 'pulse' \| 'none'`	`'shimmer'`	The idle animation. `shimmer` is a highlight travelling across the shape; `pulse` fades it in and out; `none` is a still grey box. Under `prefers-reduced-motion` all three are the still box - unlike an indeterminate progress bar, a skeleton that stops moving still says exactly what it said before, because the information is in the shape rather than in the motion.
`label`	`label`	`string`	—	A polite announcement that content is loading. Put it on one skeleton per region and leave it off the rest. See above.
`lastLine`	`last-line`	`number`	`62`	How wide the last line is, as a percentage. Shorter than the others by default, because the last line of a paragraph is - and a block of identical bars reads as a table rather than as text.
`lines`	`lines`	`number`	`1`	How many lines to draw, in `text` shape.
`shape`	`shape`	`BmxSkeletonShape`	`'text'`	What it stands in for: lines of text, a block, or an avatar.

CSS shadow parts

Part	Description
`line`	Each bar in a text skeleton.
`shape`	The single box or circle, in the other two shapes.

CSS custom properties

Property	Description
`--bmx-skeleton-color`	The grey the shapes are drawn in.
`--bmx-skeleton-duration`	One cycle of the animation.
`--bmx-skeleton-gap`	The space between lines.
`--bmx-skeleton-highlight`	The band that travels across them in `shimmer`.
`--bmx-skeleton-line-height`	How thick one line of the text shape is.
`--bmx-skeleton-radius`	The corner radius of a line or a block.
`--bmx-skeleton-size`	The circle's diameter, and the block's height when no height is given.

`<bmx-slider>`

Properties

Property	Attribute	Type	Default	Description
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the first thumb once it has rendered.
`description`	`description`	`string`	—	Help text below the track.
`disabled`	`disabled`	`boolean`	`false`	Disable the slider.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer.
`format`	property only	`BmxSliderFormatter`	—	Turns a value into what the user reads. Used for the bubble, the tick labels and `aria-valuetext` together, so the three can never disagree - a price slider that shows "£1,200" and announces "1200" is announcing a number rather than a price.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it as the accessible name.
`label`	`label`	`string`	—	The field's label. Required unless the `label` slot is used.
`largeStep`	`large-step`	`number`	—	How far Page Up and Page Down travel. Defaults to a tenth of the range.
`max`	`max`	`number`	`100`	The highest value.
`min`	`min`	`number`	`0`	The lowest value.
`minDistance`	`min-distance`	`number`	`0`	The smallest gap the two thumbs may be apart.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`orientation`	`orientation`	`BmxOrientation`	`'horizontal'`	Which way the track runs. A vertical track runs upwards.
`range`	`range`	`boolean`	`false`	Two thumbs rather than one.
`readonly`	`readonly`	`boolean`	`false`	Make the slider read-only. It still submits and is still focusable.
`showValue`	`show-value`	`BmxSliderValueDisplay`	`'auto'`	When the value is shown above the thumb.
`size`	`size`	`BmxSize`	`'md'`	Size step. Scales the track, the thumbs and the text together.
`step`	`step`	`number`	`1`	The interval between reachable values, counted from `min`.
`tickLabels`	`tick-labels`	`boolean`	`false`	Label the ticks with their values.
`ticks`	`ticks`	`number`	`0`	Draw a tick every N steps. `0` draws none. A tick per step on a long scale is thousands of elements nobody can see, so anything over a hundred draws none either.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role for the fill, the thumbs and the focus ring.
`value`	`value`	`number`	`0`	The value, in single mode. Two-way: the component writes back to it.
`values`	property only	`number[]`	`[]`	The two ends, in `range` mode. Two-way. Accepts a comma-separated or JSON string as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.

Events

Event	Detail	Description
`bmxChange`	`BmxSliderChangeDetail`	Fired when a movement finishes - on pointer release, or on each key press.
`bmxInput`	`BmxSliderChangeDetail`	Fired continuously while a thumb moves.

Methods

Method	Signature	Description
`getValues`	`getValues() => Promise<number[]>`	Every thumb's value, low to high.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from whichever thumb has it.
`setFocus`	`setFocus(index?: number, options?: FocusOptions) => Promise<void>`	Focus a thumb. The first one, unless another is named.

Slots

Slot	Description
`(default)`	The default slot
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.

CSS shadow parts

Part	Description
`bubble`	The value shown above the thumb.
`description`	The help text.
`fill`	The part of the track between the ends of the selection.
`label`	The label element.
`thumb`	A draggable thumb.
`tick`	One tick mark.
`tick-label`	One tick's text.
`track`	The full-length track.

CSS custom properties

Property	Description
`--bmx-slider-duration`	How long the thumb takes to settle after a keystroke. Zero while dragging, and under reduced motion.
`--bmx-slider-fill-color`	The selected part. Defaults to the tone's solid colour.
`--bmx-slider-font-size`	The tick labels and the value bubble.
`--bmx-slider-length`	A vertical slider's length. A horizontal one is sized by `inline-size` on the host.
`--bmx-slider-radius`	Corner radius of the track and the fill.
`--bmx-slider-thumb-border-color`	The thumb's ring. Defaults to the tone's solid colour.
`--bmx-slider-thumb-border-width`	The ring around the thumb.
`--bmx-slider-thumb-color`	The thumb's fill.
`--bmx-slider-thumb-shadow`	The thumb's shadow, which is what lifts it off the track.
`--bmx-slider-thumb-size`	The thumb's diameter.
`--bmx-slider-tick-color`	The tick marks.
`--bmx-slider-track-color`	The unfilled part of the track.
`--bmx-slider-track-size`	The track's thickness.

`<bmx-split-button>`

Properties

Property	Attribute	Type	Default	Description
`action`	property only	`(event: unknown) => unknown \| Promise<unknown>`	—	An async handler for the primary action, driving its busy state.
`disabled`	`disabled`	`boolean`	`false`	Disable both halves.
`items`	property only	`BmxMenuEntry[]`	`[]`	The menu's entries. A property, because it is an array. Accepts the JSON spelling of the list as well, because an attribute is the only channel some templates have. See `src/core/markup.ts`.
`label`	`label`	`string`	—	The primary action's accessible name, when it has no visible label.
`loading`	`loading`	`boolean`	`false`	Show the primary action as busy.
`menuLabel`	`menu-label`	`string`	`'More actions'`	The trigger's accessible name.
`placement`	`placement`	`'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end'`	`'bottom-start'`	Which side the menu opens on when there is room.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment of the outer edges.
`size`	`size`	`BmxSize`	`'md'`	Size step.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role.
`variant`	`variant`	`BmxButtonVariant`	`'solid'`	Visual treatment, applied to both halves.

Events

Event	Detail	Description
`bmxActivate`	`void`	Fired when the primary action is activated.
`bmxOpenChange`	`boolean`	Fired when the menu opens or closes.
`bmxSelect`	`BmxSplitButtonSelectDetail`	Fired when a menu item is chosen.

Methods

Method	Signature	Description
`closeMenuNow`	`closeMenuNow() => Promise<void>`	Close the menu. Focus returns to the trigger.
`openMenu`	`openMenu() => Promise<void>`	Open the menu and move focus into it.

Slots

Slot	Description
`(default)`	The primary action's label.
`start`	An icon for the primary action.

CSS shadow parts

Part	Description
`action`	The primary action button.
`base`	The container.
`item`	A menu item.
`menu`	The menu surface.
`separator`	A divider between items.
`trigger`	The menu trigger button.

CSS custom properties

Property	Description
`--bmx-button-radius`	Corner radius of the outer edges. The shared edge between the two halves is always square.
`--bmx-effect-duration`	Passed through to both halves' click effects.

`<bmx-splitter>`

Properties

Property	Attribute	Type	Default	Description
`collapseAt`	`collapse-at`	`number`	—	How far past its minimum a pane must be dragged before it folds away. Off by default, and deliberately: a pane that vanishes when a drag overshoots - and can only be brought back by finding a divider now flush against an edge - is a worse control than one that simply stops. Set it, and the pane collapses; `Enter` on the divider then folds and unfolds it, restoring the size it had rather than a default.
`collapsible`	`collapsible`	`'none' \| 'start' \| 'end' \| 'both'`	`'none'`	Which pane may collapse.
`disabled`	`disabled`	`boolean`	`false`	The divider cannot be moved.
`endMax`	`end-max`	`string \| number`	—	The most it will take.
`endMin`	`end-min`	`string \| number`	`0`	The least room the second pane will take.
`label`	`label`	`string`	`'Resize panes'`	The divider's accessible name.
`largeStep`	`large-step`	`number`	—	How far Shift and an arrow key move it. Defaults to five steps.
`orientation`	`orientation`	`BmxSplitOrientation`	`'horizontal'`	Which way the panes are stacked. `vertical` puts the first pane on top.
`position`	`position`	`string \| number`	`'50%'`	How much room the first pane gets: a length, a percentage, or a number of pixels. Reflected as it moves, so a page that wants to remember where a reader put the divider can read it off the element and write it back next time.
`snap`	`snap`	`(string \| number)[] \| string`	`''`	Positions the divider is pulled towards, as lengths or percentages. A comma-separated or JSON attribute, or an array in JavaScript. `50%` alone is a middle the divider settles into; a list gives it several. See `src/core/markup.ts` for the attribute spellings.
`snapTolerance`	`snap-tolerance`	`number`	`12`	How near a snap point the divider must be to be pulled onto it.
`startMax`	`start-max`	`string \| number`	—	The most it will take.
`startMin`	`start-min`	`string \| number`	`0`	The least room the first pane will take.
`step`	`step`	`number`	`16`	How far one arrow key press moves the divider.

Events

Event	Detail	Description
`bmxChange`	`BmxSplitterChangeDetail`	Fired when the divider is let go, or moved by a key.
`bmxInput`	`BmxSplitterChangeDetail`	Fired continuously while the divider is being dragged.

Methods

Method	Signature	Description
`collapse`	`collapse(pane?: "start" \| "end") => Promise<void>`	Fold a pane away.
`expand`	`expand() => Promise<void>`	Bring a folded pane back to the size it had.
`setPosition`	`setPosition(position: string \| number) => Promise<void>`	Put the divider somewhere. Clamped, and snapped.

Slots

Slot	Description
`end`	The second pane.
`start`	The first pane: the left one, or the top one, and the right one under RTL.

CSS shadow parts

Part	Description
`base`	The container the two panes divide.
`divider`	The bar between them.
`end`	The second pane.
`handle`	The grip drawn on the divider.
`start`	The first pane.

CSS custom properties

Property	Description
`--bmx-splitter-color`	The divider's colour.
`--bmx-splitter-color-hover`	Its colour under the pointer, and while it is being dragged.
`--bmx-splitter-handle-color`	The grip's colour.
`--bmx-splitter-handle-size`	The length of the grip drawn on it.
`--bmx-splitter-hit-area`	How far either side of the divider the pointer still grabs it.
`--bmx-splitter-size`	The divider's thickness. Also its measured gutter, so a change here changes the arithmetic.

`<bmx-switch>`

Properties

Property	Attribute	Type	Default	Description
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the switch once it has rendered.
`checked`	`checked`	`boolean`	`false`	Whether the switch is on. Two-way: the component writes back to it.
`checkedText`	`checked-text`	`string`	—	Text shown beside the track while the switch is on - "On", typically. Decoration, not the accessible state: `role="switch"` already announces on and off, so this text is hidden from assistive technology rather than read out a second time in whatever words the consumer chose. Named for `checked` rather than for "on" because Stencil rejects a property whose name begins with `on` followed by a capital - it reads it as an event handler somebody has mistakenly declared as a property, which is a good rule that happens to catch `onText`.
`description`	`description`	`string`	—	Help text below the row.
`disabled`	`disabled`	`boolean`	`false`	Disable the switch.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer.
`fullWidth`	`full-width`	`boolean`	`false`	Stretch to the width of the container, pushing the caption away from the track.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the caption visually while keeping it as the accessible name.
`label`	`label`	`string`	—	The caption. Required unless the `label` slot is used.
`labelPlacement`	`label-placement`	`BmxSwitchLabelPlacement`	`'end'`	Which side of the track the caption sits on. Logical, so RTL flips it.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`required`	`required`	`boolean`	`false`	Require the switch to be on before its form will submit.
`size`	`size`	`BmxSize`	`'md'`	Size step. Scales the track, the caption and the supporting text together.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role for the on state and the focus ring.
`uncheckedText`	`unchecked-text`	`string`	—	Text shown beside the track while the switch is off - "Off", typically.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`value`	`value`	`string`	`'on'`	What the form receives when the switch is on.

Events

Event	Detail	Description
`bmxBlur`	`void`	Fired when the switch loses focus.
`bmxChange`	`BmxSwitchChangeDetail`	Fired when the switch moves, by user action or by `toggle()`.
`bmxFocus`	`void`	Fired when the switch gains focus.
`bmxValidityChange`	`BmxSwitchValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the switch passed, without revealing anything.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the switch.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the switch if it has one.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the switch.
`toggle`	`toggle() => Promise<void>`	Move the switch, as a click would. Does nothing while it is disabled.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich caption content, in place of the `label` property.

CSS shadow parts

Part	Description
`base`	The row holding the track, the state text and the caption.
`box`	The wrapper around the control and the drawn track.
`control`	The native checkbox carrying `role="switch"`.
`description`	The help text.
`error`	The error message.
`label`	The caption.
`state`	The on/off text, when `checked-text` or `unchecked-text` is set.
`thumb`	The part of the track that moves.
`track`	The drawn track.

CSS custom properties

Property	Description
`--bmx-switch-background`	The track's background when off.
`--bmx-switch-checked-background`	The track's background when on. Defaults to the tone's solid colour.
`--bmx-switch-duration`	How long the thumb takes to travel. Zero under reduced motion.
`--bmx-switch-font-size`	The caption's font size.
`--bmx-switch-gap`	Space between the track, the state text and the caption.
`--bmx-switch-height`	The track's height. The clickable target stays at least 24px regardless.
`--bmx-switch-padding`	Space between the thumb and the inside of the track.
`--bmx-switch-support-font-size`	Font size of the description and error message.
`--bmx-switch-thumb-color`	The thumb's colour.
`--bmx-switch-thumb-shadow`	The thumb's shadow, which is what lifts it off the track.
`--bmx-switch-width`	The track's width.

`<bmx-tab-panel>`

Properties

Property	Attribute	Type	Default	Description
`active`	`active`	`boolean`	`false`	Whether this is the panel currently showing. Set by `bmx-tabs`, and reflected so a stylesheet can reach it. It is the parent's to write: a panel that made itself active would leave the strip showing a different tab as selected.
`badge`	`badge`	`string`	—	A short count or status, rendered after the label on the tab.
`disabled`	`disabled`	`boolean`	`false`	Whether the tab can be chosen.
`icon`	`icon`	`string`	—	An inline SVG string, rendered before the label on the tab.
`label`	`label`	`string`	—	The text on this panel's tab.
`value`	`value`	`string`	—	What this panel is identified by in `value` and in the event. Optional: it falls back to the label and then to the panel's position, so a set of panels written with labels alone still switches, and still reports something a consumer can distinguish.

Slots

Slot	Description
`(default)`	The panel's content.

CSS shadow parts

Part	Description
`base`	The panel itself.

CSS custom properties

Property	Description
`--bmx-tab-panel-display`	How an active panel lays its content out. Block by default.

`<bmx-tabs>`

Properties

Property	Attribute	Type	Default	Description
`activation`	`activation`	`BmxPanelActivation`	`'auto'`	Whether the arrows choose as they move, or only move.
`appearance`	`appearance`	`BmxTabsAppearance`	`'underline'`	How the strip is drawn.
`label`	`label`	`string`	`'Tabs'`	The tab list's accessible name.
`orientation`	`orientation`	`BmxOrientation`	`'horizontal'`	Which way the strip runs. Vertical moves on Up and Down instead.
`size`	`size`	`BmxSize`	`'md'`	Size step, applied to the tabs.
`stretch`	`stretch`	`boolean`	`false`	Whether the tabs share the strip's width equally.
`value`	`value`	`string`	—	The panel showing, by value. Mutable, so pressing a tab updates it. A consumer driving it may treat it as controlled and watch `bmxChange`. A value naming a panel that does not exist - or one that has been removed, or disabled - falls back to the first panel that can be shown rather than leaving the component blank.

Events

Event	Detail	Description
`bmxChange`	`BmxTabsChangeDetail`	Fired when a different panel is chosen.

Methods

Method	Signature	Description
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the selected tab.
`showPanel`	`showPanel(value: string) => Promise<void>`	Show a panel by value. Ignored if nothing has that value, or it is disabled.

Slots

Slot	Description
`(default)`	`bmx-tab-panel` elements.

CSS shadow parts

Part	Description
`panels`	The region the panels are shown in.
`tab`	One tab. The selected one also matches `tab-selected`.
`tab-badge`	The badge within a tab.
`tab-icon`	The icon within a tab.
`tab-label`	The label within a tab.
`tab-selected`	The selected tab.
`tablist`	The strip of tabs.

CSS custom properties

Property	Description
`--bmx-tab-color`	A tab's text colour when it is not selected.
`--bmx-tab-indicator-size`	Thickness of the line marking the selected tab.
`--bmx-tab-padding-block`	Space inside a tab, down.
`--bmx-tab-padding-inline`	Space inside a tab, across.
`--bmx-tab-radius`	Corner radius of a tab, in the pill and enclosed appearances.
`--bmx-tab-selected-color`	A tab's text colour when it is.
`--bmx-tabs-gap`	Space between one tab and the next.
`--bmx-tabs-panel-padding`	Space between the strip and the panel below it.

`<bmx-textarea>`

Properties

Property	Attribute	Type	Default	Description
`appearance`	`appearance`	`BmxTextareaAppearance`	`'outline'`	Visual treatment.
`autoFocus`	`auto-focus`	`boolean`	`false`	Focus the field once it has rendered.
`autocomplete`	`autocomplete`	`string`	—	Autocomplete hint.
`autosize`	`autosize`	`boolean`	`true`	Grow with the content. On by default, because the alternative is the behaviour everybody immediately writes JavaScript to replace. Turn it off for a fixed box the user resizes themselves.
`counter`	`counter`	`boolean`	`false`	Show a character counter. Pairs with `maxLength`.
`description`	`description`	`string`	—	Help text below the field.
`disabled`	`disabled`	`boolean`	`false`	Disable the field.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer - a server response, typically.
`fullWidth`	`full-width`	`boolean`	`true`	Stretch to the width of the container. On by default: text wants room.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it for assistive technology.
`label`	`label`	`string`	—	The field's label. Required unless the `label` slot is used.
`maxLength`	`max-length`	`number`	—	Maximum length, in characters rather than UTF-16 code units. Enforced here rather than by the native attribute, which counts code units and would cut a user off at fifty emoji on a limit of a hundred while the counter still read fifty. Also drives the counter's limit.
`maxRows`	`max-rows`	`number`	—	Never taller than this many rows. Beyond it the control scrolls.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`minLength`	`min-length`	`number`	—	Minimum length, in characters.
`minRows`	`min-rows`	`number`	`3`	Never shorter than this many rows.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`placeholder`	`placeholder`	`string`	—	Placeholder text. Never a substitute for a label.
`readonly`	`readonly`	`boolean`	`false`	Make the field read-only. It still submits and is still focusable.
`required`	`required`	`boolean`	`false`	Require a value.
`resize`	`resize`	`BmxTextareaResize`	`'vertical'`	The control's own resize handle. `vertical` by default rather than `both`: a textarea dragged wider than its container is the fastest way to break a form layout, and it is the one direction autosizing does not already handle. Forced to `none` while `autosize` is on, since the two fight over the same property.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment. `pill` and `circle` are not meaningful on a block.
`size`	`size`	`BmxSize`	`'md'`	Size step.
`spellcheck`	`spellcheck`	`boolean`	`true`	Spellchecking. On by default here, unlike `bmx-input`: this holds prose.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role, used for the focus ring. An error overrides it.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`validator`	property only	`BmxAsyncCheck`	—	A consumer's own check, run once the value is structurally whole.
`value`	`value`	`string`	`''`	The text in the control.
`wrap`	`wrap`	`'hard' \| 'soft' \| 'off'`	`'soft'`	Wrapping behaviour, as the native attribute takes it.

Events

Event	Detail	Description
`bmxBlur`	`void`	Fired when the field loses focus.
`bmxChange`	`BmxTextareaChangeDetail`	Fired when the field is committed - on blur.
`bmxFocus`	`void`	Fired when the field gains focus.
`bmxInput`	`BmxTextareaChangeDetail`	Fired on every edit.
`bmxValidityChange`	`BmxTextareaValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the field passed, without revealing it.
`clear`	`clear() => Promise<void>`	Empty the field.
`refreshSize`	`refreshSize() => Promise<void>`	Recompute the height now. For a value written around the component.
`removeFocus`	`removeFocus() => Promise<void>`	Remove focus from the field.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the field if it has one.
`selectAll`	`selectAll() => Promise<void>`	Select the field's contents.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the field.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.

CSS shadow parts

Part	Description
`control`	The native textarea.
`counter`	The character counter.
`description`	The help text.
`error`	The error message.
`field`	The bordered box holding the textarea.
`label`	The label element.
`spinner`

CSS custom properties

Property	Description
`--bmx-textarea-background`	The field's background. Set by `appearance`; override for a one-off.
`--bmx-textarea-border-color`	The field's border colour in its resting state.
`--bmx-textarea-border-width`	Border width of the field.
`--bmx-textarea-font-size`	The value's font size.
`--bmx-textarea-label-font-size`	The label's font size.
`--bmx-textarea-line-height`	Line height of the text. Also the row unit that minRows and maxRows count.
`--bmx-textarea-padding-block`	Vertical padding inside the field.
`--bmx-textarea-padding-inline`	Horizontal padding inside the field.
`--bmx-textarea-placeholder-color`	Placeholder colour. Dimmer than the value, and still AA against the field.
`--bmx-textarea-radius`	Corner radius of the field.
`--bmx-textarea-stack-gap`	Space between the label, the field and the supporting text.
`--bmx-textarea-support-font-size`	Font size of the description, error and counter.

`<bmx-toast>`

Properties

Property	Attribute	Type	Default	Description
`closeLabel`	`close-label`	`string`	`'Dismiss'`	The dismiss button's accessible name.
`closeOnAction`	`close-on-action`	`boolean`	`true`	Whether pressing the action closes the toast.
`dismissible`	`dismissible`	`boolean`	`true`	Whether to draw the dismiss button.
`duration`	`duration`	`number`	—	How long it stays, in milliseconds. Zero or less keeps it until dismissed. Left unset it is five seconds, ten for a toast carrying an action - which has to be read, decided on and then reached - and sticky for an `alert`.
`heading`	`heading`	`string`	—	A short bold line above the message.
`hideIcon`	`hide-icon`	`boolean`	`false`	Whether the tone's own glyph is drawn when nothing fills the icon slot.
`limit`	`limit`	`number`	`3`	How many toasts this corner shows at once. A property of the corner rather than of this toast, carried here because there is no region element for a consumer to configure. The value on whichever toast is opening is the one that applies, which is harmless in practice: an application sets these once, in the helper that creates its toasts, so every toast in a corner carries the same pair.
`open`	`open`	`boolean`	`false`	Whether the toast is asking to be on screen. Asking, rather than being: a corner already showing its limit holds this one back until a slot frees, and `open` stays true throughout - it is what the consumer asked for, and the component reports what actually happened through `bmxOpenChange`.
`position`	`position`	`BmxToastPosition`	`'bottom-end'`	Which corner it appears in. `start` and `end` mirror under RTL.
`priority`	`priority`	`BmxToastPriority`	`'status'`	How it is announced: politely, or by interrupting. `alert` is for the cases where not knowing is worse than being interrupted. It also makes the toast sticky by default.
`queueLimit`	`queue-limit`	`number`	`8`	How many may wait behind them before the oldest waiting one is dropped.
`tone`	`tone`	`BmxTone`	`'neutral'`	The semantic colour. Chosen by meaning, not by colour.

Events

Event	Detail	Description
`bmxAction`	`void`	Fired when the action was pressed, before the toast starts to leave.
`bmxClose`	`BmxToastCloseDetail`	Fired once it has finished leaving, with why it went.
`bmxOpenChange`	`boolean`	Fired when the toast reaches the screen, and when it has left it.

Methods

Method	Signature	Description
`hide`	`hide() => Promise<void>`	Hide it, whatever it is currently doing.
`show`	`show() => Promise<void>`	Show it.

Slots

Slot	Description
`(default)`	The message.
`action`	One control: Undo, Retry, View.
`heading`	A short bold line above it.
`icon`	Replaces the tone's own glyph.

CSS shadow parts

Part	Description
`action`	The wrapper around the action slot.
`close`	The dismiss button.
`content`	Heading and message together.
`heading`	The bold line.
`icon`	The glyph beside the message.
`message`	The message itself.
`surface`	The box, and the live region.

CSS custom properties

Property	Description
`--bmx-toast-accent`	The bar down the leading edge, and the icon's colour. Follows the tone by default.
`--bmx-toast-background`	The box's background.
`--bmx-toast-border-color`	Its border. Carries the shape under forced colours.
`--bmx-toast-color`	Its text colour.
`--bmx-toast-font-size`	The message's text size.
`--bmx-toast-gap`	Space between the icon, the message and the action.
`--bmx-toast-inline-size`	The box's width. It is a fixed width rather than a maximum, so a stack of them has one edge.
`--bmx-toast-inset`	How far the stack sits from the edges of the viewport.
`--bmx-toast-padding-block`	Space above and below the content.
`--bmx-toast-padding-inline`	Space either side of it.
`--bmx-toast-radius`	The corner radius.
`--bmx-toast-shadow`	The shadow under the box.
`--bmx-toast-z-index`	Only used on a browser with no top layer, where the stack has to be given one by hand.

`<bmx-toolbar>`

Properties

Property	Attribute	Type	Default	Description
`collapse`	`collapse`	`'auto' \| 'never'`	`'auto'`	Whether items that do not fit move into a menu. `never` leaves the bar to overflow however the page's CSS says it should - which is the right answer when the toolbar is inside something that already scrolls.
`label`	`label`	`string`	`'Toolbar'`	The toolbar's accessible name.
`menuLabel`	`menu-label`	`string`	`'More'`	The overflow button's accessible name.
`orientation`	`orientation`	`BmxOrientation`	`'horizontal'`	Which way the bar runs.
`wrapFocus`	`wrap-focus`	`boolean`	`true`	Whether the arrows wrap from one end of the bar to the other.

Events

Event	Detail	Description
`bmxSelect`	`BmxToolbarSelectDetail`	Fired when an item is chosen from the overflow menu.

Methods

Method	Signature	Description
`refresh`	`refresh() => Promise<void>`	Re-measure now. Rarely needed: a resize and a change of children are watched.
`setFocus`	`setFocus() => Promise<void>`	Focus the toolbar, landing on whichever item holds its tab stop.

Slots

Slot	Description
`(default)`	The toolbar's controls, and `<hr>` elements as dividers.

CSS shadow parts

Part	Description
`base`	The bar.
`menu`	The overflow menu's surface.
`trigger`	The overflow button.

CSS custom properties

Property	Description
`--bmx-toolbar-background`	The bar's background.
`--bmx-toolbar-border-color`	The bar's border, and the dividers on it.
`--bmx-toolbar-gap`	Space between one item and the next.
`--bmx-toolbar-padding`	Space inside the bar.
`--bmx-toolbar-radius`	Corner radius of the bar.
`--bmx-toolbar-separator-inset`	How far a divider stops short of the bar's edges.

`<bmx-tooltip>`

Properties

Property	Attribute	Type	Default	Description
`closeDelay`	`close-delay`	`number`	`150`	How long it stays after the last thing letting go. The bridge the pointer crosses.
`content`	`content`	`string`	—	The text. Use the default slot instead when it needs markup.
`disabled`	`disabled`	`boolean`	`false`	Nothing opens it, and the description stays on the anchor.
`distance`	`distance`	`number`	`8`	Gap between the anchor and the box, in pixels.
`for`	`for`	`string \| HTMLElement`	—	What it describes: a selector, or the element itself. Left off, the anchor is the element immediately before this one, which is what the markup above already reads like. A selector is resolved against this component's own root first, so a tooltip inside somebody else's shadow tree can still name its anchor.
`hoverable`	`hoverable`	`boolean`	`true`	Whether the pointer may move into the tooltip without closing it. On, because SC 1.4.13 requires it. Turning it off makes a long tooltip unreadable to anyone who cannot read it in one glance.
`open`	`open`	`boolean`	`false`	Whether it is on screen. Settable, for a tour or a validation hint.
`openDelay`	`open-delay`	`number`	`400`	How long the pointer rests before it opens, in milliseconds.
`placement`	`placement`	`BmxPlacement`	`'top'`	Where it prefers to sit. It flips when there is no room.
`trigger`	`trigger`	`BmxHoverTrigger`	`'both'`	How it may be opened.

Events

Event	Detail	Description
`bmxOpenChange`	`boolean`	Fired when it opens or closes, with `true` or `false`.

Methods

Method	Signature	Description
`hideTooltip`	`hideTooltip() => Promise<void>`	Hide it now.
`showTooltip`	`showTooltip() => Promise<void>`	Show it now, whatever the delays say.

Slots

Slot	Description
`(default)`	The tooltip's content, when it is more than the `content` property.

CSS shadow parts

Part	Description
`arrow`	The pointer drawn against the anchor.
`surface`	The floating box.

CSS custom properties

Property	Description
`--bmx-tooltip-arrow-size`	The pointer's size. Set it to 0 for no pointer at all.
`--bmx-tooltip-background`	The box's background.
`--bmx-tooltip-border-color`	Its border. Carries the shape under forced colours.
`--bmx-tooltip-color`	Its text colour.
`--bmx-tooltip-font-size`	The text size.
`--bmx-tooltip-max-inline-size`	How wide it may grow before wrapping. A tooltip that runs the width of the window is unreadable.
`--bmx-tooltip-padding-block`	Space above and below the text.
`--bmx-tooltip-padding-inline`	Space either side of it.
`--bmx-tooltip-radius`	Its corner radius.
`--bmx-tooltip-shadow`	The shadow under the box.

`<bmx-upload>`

Properties

Property	Attribute	Type	Default	Description
`accept`	`accept`	`string`	—	What the field takes, in the spelling a native file input accepts.
`appearance`	`appearance`	`BmxUploadAppearance`	`'outline'`	Visual treatment.
`autoUpload`	`auto-upload`	`boolean`	`true`	Start uploading as soon as files are added.
`browseText`	`browse-text`	`string`	—	The picker button's text.
`chunkSize`	`chunk-size`	`number`	`0`	Bytes per request. Zero sends each file in one. Chunking exists for the file that is too big to survive one request - a proxy's body limit, a timeout, a connection that drops at four minutes. The protocol the built-in uploader speaks is a convention, not a standard; see `upload-transport.ts`, and replace `uploader` if yours differs.
`concurrency`	`concurrency`	`number`	`3`	How many files may be in flight at once.
`description`	`description`	`string`	—	Help text below the field.
`disabled`	`disabled`	`boolean`	`false`	Disable the field.
`errorText`	`error-text`	`string`	—	An error supplied by the consumer - a server response, typically.
`fieldName`	`field-name`	`string`	`'file'`	The form field each file is sent under by the built-in uploader.
`fullWidth`	`full-width`	`boolean`	`true`	Stretch to the width of the container. On by default: a list wants room.
`headers`	property only	`Record<string, string>`	—	Extra request headers for the built-in uploader. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`hideLabel`	`hide-label`	`boolean`	`false`	Hide the label visually while keeping it for assistive technology.
`hint`	`hint`	`string`	—	Replace the generated line describing what the field accepts. The default is composed from `accept`, `maxSize` and `maxFiles`, so a field that changes its own limits cannot end up describing the old ones.
`label`	`label`	`string`	—	The field's label. Required unless the `label` slot is used.
`maxFiles`	`max-files`	`number`	—	How many files may be queued at once.
`maxSize`	`max-size`	`number`	—	Largest file allowed, in bytes.
`messages`	property only	`BmxFieldMessages`	—	Replacements for the default validity wording, by reason. Accepts the JSON spelling of the object as well, for templates that can only write attributes. See `src/core/markup.ts`.
`method`	`method`	`string`	`'POST'`	HTTP method for the built-in uploader.
`minSize`	`min-size`	`number`	—	Smallest file allowed, in bytes. Catches the empty placeholder file.
`multiple`	`multiple`	`boolean`	`false`	Accept more than one file. Off by default, as on `<input type="file">`. A single-file field replaces its file when a new one is chosen rather than refusing it.
`name`	`name`	`string`	—	The field's name in the form it belongs to.
`promptText`	`prompt-text`	`string`	`'Drag and drop files here'`	The line inside the drop zone.
`readonly`	`readonly`	`boolean`	`false`	Show the files without letting the user add or remove any.
`refusalMessages`	`refusal-messages`	`Partial<Record<BmxUploadRejection, string>> \| string`	—	Replacements for the wording of a refusal. `{name}` becomes the file name. Accepts the JSON spelling as well. The `\| string` in the type is what makes `refusal-messages` exist as an attribute - see the note on `bmx-date-picker`'s `disabledDaysOfWeek`, and `src/core/markup.ts`.
`required`	`required`	`boolean`	`false`	Require at least one file.
`shape`	`shape`	`BmxShape`	`'rounded'`	Corner treatment.
`size`	`size`	`BmxSize`	`'md'`	Size step.
`submitValue`	`submit-value`	`BmxUploadSubmitValue`	`'auto'`	What the field contributes to its form.
`tone`	`tone`	`BmxTone`	`'primary'`	Semantic colour role, used for the focus ring and the bars.
`uploader`	property only	`BmxUploader`	—	Your own transport, in place of the built-in one.
`url`	`url`	`string`	—	Endpoint for the built-in uploader. Leave unset to hold files for the form.
`validateOn`	`validate-on`	`BmxValidateOn`	`'blur'`	When the field is willing to reveal a problem.
`withCredentials`	`with-credentials`	`boolean`	`false`	Send credentials on a cross-origin upload.

Events

Event	Detail	Description
`bmxChange`	`BmxUploadChangeDetail`	Fired whenever the set of files changes.
`bmxRefuse`	`BmxUploadRefusedDetail`	Fired when files are turned away, with the reason for each.
`bmxUploadEnd`	`BmxUploadEndDetail`	Fired once when nothing is left to upload.
`bmxUploadError`	`BmxUploadFileDetail`	Fired when a file could not be uploaded.
`bmxUploadProgress`	`BmxUploadProgressDetail`	Fired as bytes move.
`bmxUploadStart`	`BmxUploadFileDetail`	Fired as each file is handed to the uploader.
`bmxUploadSuccess`	`BmxUploadFileDetail`	Fired when a file has been uploaded.
`bmxValidityChange`	`BmxUploadValidityDetail`	Fired whenever the resolved validity changes.

Methods

Method	Signature	Description
`addFiles`	`addFiles(files: File[] \| FileList) => Promise<void>`	Add files without going through the picker or a drop.
`cancelFile`	`cancelFile(id: string) => Promise<void>`	Stop a file that is uploading, or take a queued one out of the running.
`checkValidity`	`checkValidity() => Promise<boolean>`	Validate now and return whether the field passed, without revealing it.
`clear`	`clear() => Promise<void>`	Empty the queue, stopping anything in flight.
`getFiles`	`getFiles() => Promise<File[]>`	The files the field is holding, in queue order.
`getItems`	`getItems() => Promise<BmxUploadItem<File>[]>`	The queue itself - each file with its state, progress and any error.
`openPicker`	`openPicker() => Promise<void>`	Open the platform's file picker, as the button does.
`removeFile`	`removeFile(id: string) => Promise<void>`	Remove a file from the queue entirely.
`reportValidity`	`reportValidity() => Promise<boolean>`	Validate, reveal any problem, and focus the field if it has one.
`retryFile`	`retryFile(id: string) => Promise<void>`	Put a failed or cancelled file back in the queue and start it again.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focus the field's picker button.
`start`	`start() => Promise<void>`	Begin uploading. Only needed when `autoUpload` is off.

Slots

Slot	Description
`description`	Rich help text, in place of the `description` property.
`label`	Rich label content, in place of the `label` property.
`prompt`	Replaces the wording inside the drop zone.

CSS shadow parts

Part	Description
`browse`	The button that opens the file picker.
`cancel`	A row's cancel button.
`description`	The help text.
`error`	The error message.
`field`	The drop zone.
`file`	One file's row.
`file-meta`	A file's size and state.
`file-name`	A file's name.
`hint`	The line describing what the field accepts.
`label`	The label element.
`list`	The list of files.
`notices`	The live region holding refusal messages.
`overall`	The progress bar across the whole queue.
`progress`	A file's progress bar.
`remove`	A row's remove button.
`retry`	A row's retry button.

CSS custom properties

Property	Description
`--bmx-upload-background`	The zone's background.
`--bmx-upload-bar-height`	Thickness of the progress bars.
`--bmx-upload-bar-track`	The unfilled part of a progress bar.
`--bmx-upload-border-color`	The zone's border colour in its resting state.
`--bmx-upload-border-width`	Border width of the drop zone.
`--bmx-upload-drop-background`	The zone's background while a drag is over it.
`--bmx-upload-font-size`	Base font size for the zone and the file list.
`--bmx-upload-label-font-size`	The label's font size.
`--bmx-upload-list-max-block-size`	Height at which the file list starts scrolling.
`--bmx-upload-padding-block`	Vertical padding inside the drop zone.
`--bmx-upload-padding-inline`	Horizontal padding inside the drop zone.
`--bmx-upload-radius`	Corner radius of the zone and the file rows.
`--bmx-upload-row-background`	Background of a file row.
`--bmx-upload-stack-gap`	Space between the label, the zone, the list and the supporting text.
`--bmx-upload-support-font-size`	Font size of the description, error, hint and file meta.