bM Binarymission.NET, Web & AI Products
Contact Get a License
v1.6.0

API reference

Every property, event, method, slot, part and custom property in the library — 1738 in total, generated from the components' own source. Filter it below.

<bmx-accordion>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxChange BmxAccordionChangeDetail Fired when a panel opens or closes.

Methods

MethodSignatureDescription
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

SlotDescription
(default) bmx-accordion-item elements.

CSS shadow parts

PartDescription
base The container.

CSS custom properties

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxToggle BmxAccordionToggleDetail Fired when the item opens or closes.

Methods

MethodSignatureDescription
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

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

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

SlotDescription
(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

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

SlotDescription
(default) bmx-avatar elements.

CSS shadow parts

PartDescription
group The row.
more The counter.

CSS custom properties

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

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

CSS shadow parts

PartDescription
anchor The box the slotted content sits in.
badge The bubble.

CSS custom properties

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxSelect BmxBreadcrumbSelectDetail Fired when a crumb is chosen from the overflow menu.

Methods

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

Slots

SlotDescription
(default) The crumbs, in order, root first.

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

MethodSignatureDescription
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

SlotDescription
(default) The crumb's label.
prefix An icon before the label.

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
(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

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxChange BmxButtonGroupChangeDetail Fired when the selection changes. Not fired in selection="none".

Methods

MethodSignatureDescription
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

SlotDescription
(default) bmx-button elements, or any focusable controls.

CSS shadow parts

PartDescription
base The group container.

CSS custom properties

PropertyDescription
--bmx-button-group-gap Space between items when the group is not attached.

<bmx-calendar>

Properties

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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
empty Shown when there is nothing in view at all.

CSS shadow parts

PartDescription
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

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

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxAutoplayChange BmxCarouselAutoplayDetail The clock started or stopped, and why.
bmxChange BmxCarouselChangeDetail The slide changed.

Methods

MethodSignatureDescription
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

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

CSS shadow parts

PartDescription
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

PropertyDescription
--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-chart>

Properties

PropertyAttributeTypeDefaultDescription
animated animated boolean true Draw the marks in when the data arrives. Off when the reader asks for less motion.
annotations annotations readonly BmxChartAnnotation[] | string — Lines and bands across the plot: [{ value, label }], [{ type: 'band', axis: 'x', from, to }]. JSON in markup.
bins bins number — A histogram's number of bins. Default: Sturges' rule.
data data BmxChartData | readonly Record<string, unknown>[] | string — The numbers: { categories, series: [{ name, values }] }, series of points (x a number or a date), tree, nodes and links, or a gauge's value. Or an array of records, with xField and yFields. JSON in markup.
dataLabels data-labels boolean false Write the values on the bars, points and slices.
depth depth number 2 A treemap's levels shown at once. Default 2.
description description string — A line under the title, also read with the chart.
format format BmxChartNumberFormat | string — How values are written unless a series says otherwise: percent, currency:EUR, decimal:2, compact, or { style, currency, decimals, prefix, suffix }.
innerRadius inner-radius number 0.6 A doughnut's hole, as a share of its radius. Default 0.6.
label label string — A title over the chart, and its accessible name.
legend legend 'bottom' | 'top' | 'end' | 'none' 'bottom' Where the legend goes: bottom (default), top, end or none.
locale locale string — A BCP 47 locale for numbers and dates. Default: the page's lang.
patterns patterns boolean false Fill each series with a pattern as well as a colour, so they can be told apart without colour.
renderer renderer 'auto' | 'svg' | 'canvas' 'auto' auto (default: a canvas past a few thousand points), svg or canvas.
seriesField series-field string — With records: a column whose values each become a series (of the first of yFields).
stack stack 'none' | 'normal' | 'percent' 'none' Stack columns, bars and areas: none (default), normal, or percent (each to a hundred per cent).
strings strings Partial<BmxChartStrings> | string — Words the chart shows or says, to translate or reword: any of BmxChartStrings. JSON in markup.
timeZone time-zone string — The IANA time zone a time axis is read in. Default: the reader's.
toolbar toolbar boolean false Show buttons over the chart: switch to the data table, download PNG, SVG or CSV.
tooltip tooltip 'auto' | 'item' | 'axis' | 'none' 'auto' auto (default: one value for points and bars, every series at once on a line or area), item, axis or none.
type type BmxChartType 'column' What kind of chart. Default column.
xAxis x-axis BmxChartAxisOptions | string — The x axis: { title, type, min, max, grid, hidden }. JSON in markup.
xField x-field string — With records: the column along the x axis.
y2Axis y-2-axis BmxChartAxisOptions | string — The second value axis, on the far side, for series with axis: 'y2'.
yAxis y-axis BmxChartAxisOptions | string — The value axis: { title, min, max, log, zero, grid, hidden }. JSON in markup.
yFields y-fields readonly string[] | string — With records: the columns to chart, each a series (a list, or comma-separated in markup).
zoom zoom boolean false Drag across the plot to zoom in on that stretch of the x axis (lines, areas, columns, scatter, candles). Ctrl and the wheel zoom too.

Events

EventDetailDescription
bmxChartDrill BmxChartDrillDetail A treemap was drilled into, or back out.
bmxChartLegendToggle BmxChartLegendToggleDetail A series or category was switched on or off.
bmxChartSelect BmxChartSelectDetail A mark was chosen.
bmxChartZoom BmxChartZoomDetail The x axis was zoomed, or the zoom reset.

Methods

MethodSignatureDescription
download download(format?: "png" | "svg" | "csv", filename?: string) => Promise<void> Saves the chart as png, svg or csv, under filename (default: the label).
drillDown drillDown(path: readonly string[]) => Promise<void> Drills a treemap to a path of names ([] for the top).
getTable getTable() => Promise<BmxChartTable> The numbers as a table: { headers, rows, total }.
resetZoom resetZoom() => Promise<void> Shows the whole x axis again.
setFocus setFocus() => Promise<void> Moves focus to the chart.
setSeriesVisible setSeriesVisible(index: number, visible: boolean) => Promise<void> Shows or hides a series, as its legend entry does.
setZoom setZoom(from: number | string | Date, to: number | string | Date) => Promise<void> Zooms the x axis to from-to, in data units (a category's index, a number, or an instant or ISO date).
toCSV toCSV() => Promise<string> The numbers as CSV.
toPNG toPNG(scale?: number) => Promise<Blob> The chart as a PNG, scale times its size on screen (default 2).
toSVG toSVG() => Promise<string> The chart as a standalone SVG document, its colours and fonts written in, with its title and legend.

CSS shadow parts

PartDescription
breadcrumb a treemap's path when drilled in.
caption its title.
chart the whole chart.
description the line under the title.
legend the series.
legend-item one series or category, a button that shows or hides it.
plot the drawing.
table the data table, when it is shown.
toolbar the buttons above the plot.
tooltip the values under the pointer.

CSS custom properties

PropertyDescription
--bmx-chart-area-opacity How solid an area is. Default 0.22.
--bmx-chart-background Behind the chart.
--bmx-chart-color-0 The first series (or slice). Colours 0 to 9 are used in turn.
--bmx-chart-color-1 The second series.
--bmx-chart-color-2 The third series.
--bmx-chart-color-3 The fourth series.
--bmx-chart-color-4 The fifth series.
--bmx-chart-color-5 The sixth series.
--bmx-chart-color-6 The seventh series.
--bmx-chart-color-7 The eighth series.
--bmx-chart-color-8 The ninth series.
--bmx-chart-color-9 The tenth series.
--bmx-chart-down A falling candle, and a waterfall's decrease.
--bmx-chart-grid The grid lines.
--bmx-chart-heat-high A heatmap's highest value.
--bmx-chart-heat-low A heatmap's lowest value.
--bmx-chart-height How tall the drawing is. Default 20rem.
--bmx-chart-up A rising candle, and a waterfall's increase.

<bmx-chat>

Properties

PropertyAttributeTypeDefaultDescription
accept accept string — The files allowed, as an <input type="file"> accept ("image/*,.pdf").
allowImages allow-images boolean false Show images an answer's Markdown points to. Off by default, so an answer cannot load anything.
assistantAvatar assistant-avatar string — The assistant's picture. Default: a mark drawn by the library.
assistantName assistant-name string — The assistant's name.
attachments attachments boolean false Let the reader send files.
busy busy boolean false A reply is being written. Set by the chat while its handler runs; set it yourself when writing replies without one.
description description string — A line under the title.
disabled disabled boolean false Show the text box, but disabled.
feedback feedback boolean true Offer good and poor buttons on answers.
handler property only BmxChatHandler — Writes each reply: given the conversation and a signal, returns text, a stream, or a fetch response.
heading heading string — A title shown before the first message ("How can I help?").
label label string — What the conversation is, for screen readers.
locale locale string — A BCP 47 locale for times and dates. Default: the page's lang.
maxAttachmentSize max-attachment-size number 20 * 1024 * 1024 The largest file, in bytes. Default 20 MB.
maxAttachments max-attachments number 5 At most this many files per message.
maxLength max-length number — At most this many characters in a message.
messages messages readonly BmxChatMessage[] | string [] The conversation. JSON in markup. Updated as messages are sent and answered.
placeholder placeholder string — Shown in the text box while it is empty.
readonly readonly boolean false Show the conversation without the text box.
sendOnEnter send-on-enter boolean true Enter sends (Shift+Enter is a new line). Off: Ctrl+Enter or Cmd+Enter sends.
strings strings Partial<BmxChatStrings> | string — Words the chat shows or says: any of BmxChatStrings. JSON in markup.
suggestions suggestions readonly string[] | string — Messages the reader can send with one click: a list, or comma-separated in markup.
userAvatar user-avatar string — The reader's picture.
userName user-name string — The reader's name, on their own messages.
voice voice boolean false Offer a microphone button that writes what is said, using the browser's speech recognition (some browsers send the audio to their maker's service).

Events

EventDetailDescription
bmxChatError BmxChatErrorDetail A reply failed.
bmxChatFeedback BmxChatFeedbackDetail The reader rated an answer.
bmxChatMessagesChange BmxChatMessagesDetail The conversation changed. messages is the whole new list.
bmxChatReply BmxChatMessageDetail A reply was finished.
bmxChatRetry BmxChatMessageDetail The reader asked for an answer again (with no handler, write it yourself).
bmxChatSend BmxChatSendDetail The reader sent a message (cancelable).
bmxChatStop BmxChatMessageDetail | null The reader pressed Stop.

Methods

MethodSignatureDescription
addMessage addMessage(message: Partial<BmxChatMessage>) => Promise<string> Adds a message (any role) and returns its id.
appendToMessage appendToMessage(id: string, text: string) => Promise<void> Adds text to the end of a message, as a reply streams in.
clear clear() => Promise<void> Empties the conversation.
download download(format?: "md" | "txt" | "json", filename?: string) => Promise<void> Saves the conversation as md, txt or json.
finishReply finishReply(id: string, status?: "done" | "error" | "stopped", error?: string) => Promise<void> Ends a reply started with startReply.
getMessages getMessages() => Promise<readonly BmxChatMessage[]> The conversation.
scrollToLatest scrollToLatest() => Promise<void> Scrolls to the latest message.
send send(text: string, files?: readonly File[]) => Promise<void> Sends a message as the reader, as if typed. Resolves when its reply (if any) is done.
setFocus setFocus() => Promise<void> Moves focus to the text box.
startReply startReply(message?: Partial<BmxChatMessage>) => Promise<string> Starts a reply written by the application (with no handler): returns its id, and marks the chat busy.
stop stop() => Promise<void> Stops the reply being written.
toMarkdown toMarkdown() => Promise<string> The conversation as Markdown.
toText toText() => Promise<string> The conversation as plain text.
updateMessage updateMessage(id: string, patch: Partial<BmxChatMessage>) => Promise<void> Changes a message.

CSS shadow parts

PartDescription
avatar an author's picture or initials.
bubble a message's text.
composer where the reader writes.
empty what shows before the first message.
input the text box.
log the conversation.
message one message.
send the send (and stop) button.
suggestions the suggested messages.

CSS custom properties

PropertyDescription
--bmx-chat-background Behind the conversation.
--bmx-chat-bubble Everyone else's messages.
--bmx-chat-height How tall the chat is. Default 32rem.
--bmx-chat-max-width The widest a message grows. Default 46rem.
--bmx-chat-user-bubble The reader's own messages.
--bmx-chat-user-text Text on the reader's messages.

<bmx-checkbox>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
description Rich help text, in place of the description property.
label Rich caption content, in place of the label property.

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

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

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

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

Slots

SlotDescription
(default) bmx-chip elements.

CSS shadow parts

PartDescription
more The counter chip.
set The row.

CSS custom properties

PropertyDescription
--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-more-background The background of the overflow "+n" chip.
--bmx-chip-set-more-color Its text.
--bmx-chip-set-row-gap The space between rows, when the set wraps.

<bmx-combobox>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
(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

PartDescription
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

PropertyDescription
--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-data-grid>

Properties

PropertyAttributeTypeDefaultDescription
allowPivot allow-pivot boolean false A Pivot button in the toolbar, so the reader can pivot the rows themselves.
appearance appearance BmxGridAppearance 'modern' The look: modern, striped, bordered, minimal, glass or cards.
blockSize block-size number 100 Rows fetched per request from dataProvider.
cardBreakpoint card-breakpoint number 600 The width in pixels below which presentation="auto" shows cards.
cardFields card-fields string | string[] — The fields a card shows, separated by spaces; the first is the card's title. Default: the first six columns shown.
checkboxes checkboxes boolean false Show a checkbox column for choosing rows.
columnMenu column-menu boolean true Each heading's menu: sort, filter, group, pin, hide.
columns columns BmxGridColumn[] | string [] The columns: { field, title?, type?, ... }, or JSON in the attribute. Read from the data when empty.
contextMenu context-menu boolean true The menu on a right-click, Shift+F10 or the menu key over a cell.
contextMenuItems property only BmxGridMenuItem[] | ((context: BmxGridMenuContext) => BmxGridMenuItem[]) — Your own commands for that menu, after the grid's: a list of { id, label, icon?, disabled?, separator? }, or a function of the cell and rows that returns one. The choice arrives as bmxGridMenuAction.
dataProvider property only BmxGridDataProvider — Rows from your server, a block at a time: called with { start, count, sort, filters, search, signal }, answers { rows, total }. The sort, filters and search are then the server's to apply. Set from script.
density density BmxGridDensity 'standard' Row height: compact, standard or comfortable.
detailGrid detail-grid BmxGridDetailGrid | string — A grid of a row's own rows in its panel: { field, columns, readonly? }, or JSON.
detailHeight detail-height number 260 The height of a row's detail panel, in pixels.
detailRenderer property only (row: BmxGridRow, container: HTMLElement) => string | Node | void — Fills the panel under a row opened with its expander: return text or a node, or fill container yourself. Set from script.
emptyText empty-text string — What to say when there are no rows.
enterMoves enter-moves 'down' | 'right' | 'none' 'down' Where Enter goes after an edit: down, right or none.
fileName file-name string 'data' The name exported files are saved under.
fillHandle fill-handle boolean true Drag the corner of the chosen cells to fill on down or across, as a spreadsheet does.
filterRow filter-row boolean false Show a row of filters under the headings.
filters filters BmxGridFilter[] | string [] Column filters: [{ field, op, value }], or JSON.
flashChanges flash-changes boolean true Flash cells that updateRows changes.
footer footer boolean true Show the totals row, when any column has an aggregate.
formatRules format-rules BmxGridFormatRule[] | string [] Conditional formatting as data: [{ field, when: { op, value }, style: { tone, bold } }], or JSON.
formulaEngine formula-engine string — A bmx-formula-engine (its id, or a selector) whose workbook holds the grid's sheet, so formulas on the page and in the grid can use each other: =Rates!B2 here, =SUM(Data[Amount]) there. Default: a workbook of the grid's own.
frozenRows frozen-rows number 0 Rows kept at the top whatever the scroll: the first this many lines.
groupBy group-by string | string[] '' Fields to group by, outermost first: "region status" or a list.
groupPanel group-panel boolean true Show the bar that headings are dragged to, to group by them.
groupsExpanded groups-expanded boolean true Groups start open.
label label string — The accessible name. Default: "Data".
liveSrc live-src string — A WebSocket (ws:, wss:) or server-sent events URL whose messages update rows.
liveType live-type 'auto' | 'websocket' | 'sse' 'auto' What liveSrc is. auto goes by the URL's scheme.
loading loading boolean false Show a loading bar. Set while your own data is on its way.
locale locale string — A BCP 47 locale for numbers, money and dates. Default: the page's lang, then the reader's.
page page number 1 The page on show, from 1.
pageSize page-size number 50 Rows on a page.
pagination pagination boolean false Show rows a page at a time, with a pager, instead of one long scroll.
parentField parent-field string — Tree data, flat: the field holding each row's parent's key (by rowKey).
pinnedRows pinned-rows unknown[] | string [] Rows pinned at the top, by key: they stay in view as the rest scroll.
pivot pivot BmxGridPivot | string — Pivot the rows: { rows: [...], columns: [...], values: [{ field, aggregate }] }, or JSON. Empty for the rows as they are.
presentation presentation 'auto' | 'table' | 'cards' 'auto' table, cards (one card per row, for small screens), or auto: cards when the grid is narrower than cardBreakpoint.
rangeSelection range-selection boolean true Choose rectangles of cells with Shift and the mouse: to copy, paste over, clear and total.
readonly readonly boolean false Nothing can be edited, added or removed. The grid is editable by default.
requestInit property only RequestInit — Options for fetching src: headers, credentials.
rowKey row-key string 'id' The field that identifies a row, for selection, updates and changes. Rows without it are known by themselves.
rowNumbers row-numbers boolean false Show a column of row numbers.
rowReorder row-reorder boolean false Rows are moved by dragging their handle, or with Alt+Shift and the up and down arrows.
rowSelection row-selection 'none' | 'single' | 'multiple' 'multiple' How rows are chosen: none, single or multiple.
rows rows BmxGridRow[] | string [] The rows: an array of objects, or JSON in the attribute. Edits are written into these objects.
search search string '' The quick search: rows with every word, in any column.
sheetName sheet-name string 'Data' The name of the grid's sheet in its workbook, and of the table its rows make (Data[Amount]).
sort sort string | BmxGridSort[] '' Sort keys: "region total:desc", or [{ field, direction }].
spreadsheet spreadsheet boolean false Spreadsheet mode: columns get letters and rows numbers, as on a worksheet - the titles are row 1, so the first row is row 2 - and any editable cell takes a formula typed with =: =B2*C2, =SUM(D2:D20), =[@Price]*1.2. The row keeps the formula; the grid shows, sorts, filters, totals and exports its value, and the Excel export carries the formulas. Clicking cells while a formula is typed puts references in, each outlined in its colour. A bmx-formula-bar given the grid as its engine edits the active cell.
src src string — A URL to load the rows from: JSON, JSON lines, CSV or TSV.
stateKey state-key string — A name to keep the reader's view under in this browser: sort, filters, columns, grouping.
statusBar status-bar boolean true Show the counts, the changes and the totals of the chosen cells under the grid.
timeZone time-zone string — An IANA zone for times, or utc. Default: the reader's.
toolbar toolbar boolean true Show the toolbar: search, columns, grouping, export, undo.
treeColumn tree-column string — The column that shows the tree's branches. Default: the first column of data.
treeExpanded tree-expanded boolean false Tree rows start open.
treeField tree-field string — Tree data, nested: the field holding each row's children.

Events

EventDetailDescription
bmxGridActiveCellChange BmxGridActiveCellDetail The active cell moved.
bmxGridCellAction BmxGridCellActionDetail A cell's button was pressed.
bmxGridCellChange BmxGridCellChangeDetail A cell is about to change: by an edit, a paste, a clear, undo or redo. Cancelable.
bmxGridCellPress BmxGridCellPressDetail Spreadsheet mode: a cell was pressed, or dragged on from. Cancel it to take the press - a formula bar does, to put references in its formula.
bmxGridColumnChange BmxGridColumnChangeDetail Columns were resized, moved, pinned, hidden or shown.
bmxGridConnection BmxGridConnectionDetail The live connection opened, dropped, is being tried again, or closed.
bmxGridContextMenu BmxGridMenuContext The context menu is about to open. Cancel to show your own instead.
bmxGridDataChange BmxGridDataChangeDetail The data changed. One event per gesture: a paste of a hundred cells is one.
bmxGridDetailEvent BmxGridDetailEventDetail Something happened in a detail panel's grid: its event, carried out.
bmxGridDetailToggle BmxGridDetailToggleDetail A row's detail panel opened or closed.
bmxGridEditStart BmxGridEditStartDetail An edit is about to start. Cancelable.
bmxGridFilterChange BmxGridFilterChangeDetail The filters or the search changed.
bmxGridGroupChange BmxGridGroupChangeDetail The grouping changed.
bmxGridLoad BmxGridLoadDetail Rows arrived from src, a file or the provider, or loading failed.
bmxGridMenuAction BmxGridMenuActionDetail A command of your own was chosen from the context menu.
bmxGridPageChange BmxGridPageChangeDetail The page on show changed.
bmxGridPivotChange BmxGridPivotChangeDetail The pivot changed.
bmxGridRowActivate BmxGridRowActivateDetail A row was opened.
bmxGridRowMove BmxGridRowMoveDetail A row is about to move. Cancelable.
bmxGridRowsRemove BmxGridRowsRemoveDetail Rows are about to be removed. Cancelable.
bmxGridSelectionChange BmxGridSelectionChangeDetail The chosen rows changed.
bmxGridSortChange BmxGridSortChangeDetail The sort changed.
bmxGridStateChange BmxGridStateChangeDetail The view changed: sort, filters, search, columns, grouping.
bmxGridTreeToggle BmxGridTreeToggleDetail A tree row opened or closed.

Methods

MethodSignatureDescription
acceptChanges acceptChanges(options?: { clearHistory?: boolean; }) => Promise<void> Treats the data as it is now as saved: nothing counts as changed any more. Undo and redo still work across the save, and whatever they change is then reported by getChanges for saving again; clearHistory forgets them as well.
addRow addRow(row?: BmxGridRow, index?: number, edit?: boolean) => Promise<BmxGridRow | null> Adds a row (an empty one by default) at a position among all rows, and returns it. With edit, it is scrolled to and its first editable cell opened.
applyLiveMessage applyLiveMessage(message: unknown) => Promise<void> Applies one message as if it had come from liveSrc: for a feed of your own (SignalR, socket.io, a worker) in the same shape - an array of rows, or { op: 'upsert' | 'remove' | 'replace', rows | row | keys } - as an object or its JSON text.
autosizeColumns autosizeColumns(fields?: readonly string[]) => Promise<void> Fits columns to their contents: these fields, or all.
clearFilters clearFilters() => Promise<void> Clears every filter and the search.
clearSelection clearSelection() => Promise<void> Chooses no rows.
collapseAll collapseAll() => Promise<void> Closes every group, or every tree row.
connectLive connectLive(url?: string, type?: "auto" | "websocket" | "sse") => Promise<void> Connects to a live source (default liveSrc) whose messages update rows.
disconnectLive disconnectLive() => Promise<void> Closes the live connection.
download download(format?: BmxGridExportFormat, options?: BmxGridExportOptions) => Promise<void> Exports and saves the file, named by fileName.
editCell editCell(rowOrKey: BmxGridRow | unknown, field: string) => Promise<boolean> Starts editing a cell. False when it cannot be edited.
expandAll expandAll() => Promise<void> Opens every group, or every tree row.
exportData exportData(format?: BmxGridExportFormat, options?: BmxGridExportOptions) => Promise<Blob> The rows on show as a file: xlsx, csv, tsv or json.
getCellAddress getCellAddress(rowOrKey?: BmxGridRow | unknown, field?: string) => Promise<string | null> A cell's sheet address (Data!B3), or the active cell's when no row is given. Null without formulas.
getChanges getChanges() => Promise<BmxGridChanges> What was added, changed and removed since the rows were loaded or the changes last accepted.
getFormulaWorkbook getFormulaWorkbook() => Promise<BmxFormulaWorkbook | null> The formula workbook the grid's sheet is on, while it has formulas (spreadsheet mode or formula columns): the grid's own, or the formulaEngine's. Null otherwise.
getPrintHtml getPrintHtml() => Promise<string> The printable document print() uses, as HTML: for a print preview of your own, or a PDF made on a server.
getRows getRows() => Promise<BmxGridRow[]> Every row, in the order given.
getSelectedRows getSelectedRows() => Promise<BmxGridRow[]> The chosen rows.
getShownRows getShownRows() => Promise<BmxGridRow[]> The rows kept by the filters and search, in the order shown.
getState getState() => Promise<BmxGridState> Everything the reader has changed about the view, to save and give back to setState.
goToCell goToCell(address: string) => Promise<boolean> Moves the active cell to a sheet address (B3, Data!B3) and shows it. False when the row is filtered out or the column hidden.
goToPage goToPage(page: number) => Promise<void> Shows a page, from 1, when pagination is on.
load load(source: string | URL | Blob) => Promise<void> Loads rows from a URL, a File or Blob (a chosen or dropped file), or text: JSON, JSON lines, CSV or TSV. Replaces the rows; columns are read from the data when none were given.
moveRow moveRow(rowOrKey: BmxGridRow | unknown, before: BmxGridRow | unknown | null) => Promise<boolean> Moves a row to before another (objects or keys), or to the end with null, as dragging its handle does. False when rows cannot move now.
openFile openFile() => Promise<void> Opens the browser's file picker to load a CSV, TSV or JSON file.
pinColumn pinColumn(field: string, side: "start" | "end" | null) => Promise<void> Pins a column to the start or end, or unpins it with null.
print print() => Promise<void> Opens the print dialog for the rows on show: the columns shown, every row the filters keep, groups open, headings on every page.
redo redo() => Promise<boolean> Does again what was undone.
refresh refresh() => Promise<void> Runs the sort, filters and grouping again: after changing rows in place. For a server source, asks again.
removeRows removeRows(rows: readonly (BmxGridRow | unknown)[]) => Promise<number> Removes rows, by the row objects or their keys. Returns how many went.
revertChanges revertChanges() => Promise<void> Puts back every change since the rows were loaded or the changes last accepted.
scrollToRow scrollToRow(rowOrKey: BmxGridRow | unknown, field?: string) => Promise<boolean> Scrolls to a row (the object, its key, or its position among the rows on show) and makes it active.
selectAll selectAll() => Promise<void> Chooses every row the filters keep.
selectRows selectRows(rows: readonly (BmxGridRow | unknown)[], add?: boolean) => Promise<void> Chooses rows, by the row objects or their keys; add keeps those already chosen.
setCellText setCellText(address: string, text: string) => Promise<boolean> Sets a cell, given by its sheet address, from text as a reader types it: read and checked as the cell's editor would, kept for undo and reported by the usual events. In spreadsheet mode, = starts a formula. False when the text is refused or there is no such editable cell.
setCellValue setCellValue(rowOrKey: BmxGridRow | unknown, field: string, value: unknown) => Promise<boolean> Sets one cell, as an edit would: validated, cancelable, undoable. False when refused.
setColumnHidden setColumnHidden(field: string, hidden: boolean) => Promise<void> Shows or hides a column.
setColumnWidth setColumnWidth(field: string, width: number) => Promise<void> Sets a column's width in pixels, as dragging its edge does.
setFilter setFilter(field: string, filter: Omit<BmxGridFilter, "field"> | null) => Promise<void> Sets a column's filter, or clears it with null.
setFocus setFocus() => Promise<void> Moves focus into the grid.
setGroupBy setGroupBy(fields: readonly string[]) => Promise<void> Groups by these fields, outermost first; an empty list stops grouping.
setPivot setPivot(pivot: BmxGridPivot | null) => Promise<void> Pivots the rows, or shows them as they are with null.
setState setState(state: BmxGridState | string) => Promise<boolean> Restores a view saved by getState (an object or its JSON). False when it could not be read.
showReferences showReferences(references?: readonly BmxGridReference[]) => Promise<void> Outlines references in spreadsheet mode, each in its colour - what a formula bar editing the grid's cells shows. An empty list clears them.
sortBy sortBy(field: string, direction?: "asc" | "desc" | null, add?: boolean) => Promise<void> Sorts by a column: asc, desc, or null to stop. add keeps the other sort keys.
stopEdit stopEdit(cancel?: boolean) => Promise<void> Closes the editor: commits the value, or with cancel keeps the old one.
toggleDetail toggleDetail(rowOrKey: BmxGridRow | unknown, open?: boolean) => Promise<boolean> Shows or hides a row's detail panel; toggles without open.
toggleRow toggleRow(rowOrKey: BmxGridRow | unknown, open?: boolean) => Promise<boolean> Opens or closes a tree row (the object or its key); toggles without open. False when it has no rows inside.
undo undo() => Promise<boolean> Undoes the last change. False when there is nothing to undo.
updateRows updateRows(rows: readonly BmxGridRow[]) => Promise<{ updated: number; added: number; }> Updates rows from newer copies, matched by rowKey: changed values are written in and flash (green up, red down for numbers). Rows with a new key are added at the end. For live data - prices, statuses, counters.

Slots

SlotDescription
(default) a <table> to read the columns and rows from.
empty what to show when there are no rows.
toolbar-end your own controls at the end of the toolbar.
toolbar-start your own controls at the start of the toolbar.

CSS shadow parts

PartDescription
clear-filters
context-menu
edit-error
empty
error
frame
grid
group-chip
group-panel
live-badge
loading
menu
menu-item
pager
pager-button
pager-size
pivot-panel
search
search-input
status
tool-button
toolbar

CSS custom properties

PropertyDescription
--bmx-data-grid-active The ring around the active cell.
--bmx-data-grid-background Behind the rows.
--bmx-data-grid-card-background A card, when rows are shown as cards. @part toolbar - the bar of tools above the grid. @part tool-button - a tool. @part search - the quick search. @part search-input - its field. @part group-panel - the bar headings are dragged to, to group by them. @part group-chip - a field the rows are grouped by. @part frame - the box around the grid. @part grid - the scrolling grid. @part header-row - the headings. @part header-band-row - the row of bands over grouped headings. @part header-band - one band. @part header-cell - one heading. @part header-menu - a heading's menu button. @part resizer - the edge dragged to resize a column. @part filter-row - the row of filters under the headings. @part filter-input - one filter. @part filter-button - a filter by a list of values. @part cell - a cell. Also cell-<type> (cell-currency, cell-status), cell-active, cell-dirty and cell-<tone> from cellTone. @part group-row - a group's heading. @part group-count - the number of rows in a group. @part footer-row - the totals. @part footer-cell - one total. @part badge - a status, badge, priority or choice. Also badge-<tone>. @part chip - a tag. @part bar - a progress bar, meter or data bar. @part rating - the stars. @part avatar - a person's picture or initials. @part image - a picture. @part swatch - a colour. @part timeline - a timespan's track. @part link - a link. @part checkbox - a checkbox. @part switch - a switch. @part cell-button - a cell's button. @part action - a row action. @part match - a search match. @part editor - the field a cell is edited in. @part edit-error - why an edit was refused. @part menu - a pop-up: a column's menu, the columns, export, row height, the context menu, the pivot panel. @part context-menu - the menu on a right-click over a cell. @part pivot-panel - the panel that pivots the rows. @part detail - a row's detail panel. @part card - a row shown as a card. @part fill-handle - the square at the corner of the chosen cells, dragged to fill. @part row-drop - where a dragged row would land. @part pager - the page controls. @part pager-button - one of them. @part pager-size - the rows-per-page choice. @part live-badge - the state of the live connection. @part menu-item - one of its commands. @part status - the counts under the grid. @part clear-filters - the button that clears every filter. @part empty - what is shown when there are no rows. @part error - what is shown when the rows could not be loaded. @part loading - the loading bar. @part column-letter - a column's letter in spreadsheet mode.
--bmx-data-grid-cell-padding Space either side of a cell's content.
--bmx-data-grid-detail-background Around a row's detail panel.
--bmx-data-grid-font-size The cells' text size.
--bmx-data-grid-footer-background The totals row.
--bmx-data-grid-group-background A group's heading row.
--bmx-data-grid-header-background Behind the headings.
--bmx-data-grid-header-height The headings' height.
--bmx-data-grid-header-text The headings' text.
--bmx-data-grid-height How tall the grid is, toolbar and status included.
--bmx-data-grid-line The lines between rows and columns.
--bmx-data-grid-pinned-background A row pinned to the top.
--bmx-data-grid-radius The corners of the grid.
--bmx-data-grid-range The chosen cells.
--bmx-data-grid-row-alternate Every other row, in the striped look.
--bmx-data-grid-row-background A row.
--bmx-data-grid-row-height Each row's height. Set it to override the density.
--bmx-data-grid-row-hover A row under the pointer.
--bmx-data-grid-row-selected A chosen row.
--bmx-data-grid-scrollbar-thumb The scrollbars' thumbs.
--bmx-data-grid-scrollbar-track The scrollbars' tracks.
--bmx-data-grid-tree-indent How far each level of a tree is indented.

<bmx-date-picker>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
(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

PartDescription
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

PropertyDescription
--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-diagram>

Properties

PropertyAttributeTypeDefaultDescription
connector connector BmxDiagramRoute 'orthogonal' How new connectors are drawn.
diagram diagram Partial<BmxDiagramData> | string — The diagram: nodes, edges and lanes. JSON in markup. Kept up to date as it is edited.
grid grid number 20 The grid spacing; 0 hides it.
label label string — What the diagram is, for screen readers.
mermaid mermaid string — A Mermaid flowchart to start from, when diagram is empty.
readonly readonly boolean false Show the diagram to read, pan and zoom, without editing.
shapes shapes readonly BmxDiagramShapeCategory[] | string ['flowchart', 'basic', 'bpmn', 'network'] The shape groups in the palette, in order: any of flowchart, basic, bpmn, network.
snap snap boolean true Shapes snap to the grid as they move.
strings strings Partial<BmxDiagramStrings> | string — Words the designer shows or says: any of BmxDiagramStrings. JSON in markup.
toolbar toolbar boolean true Show the command bar.
validateConnection property only BmxDiagramConnectionCheck — Decides whether two nodes may be connected.

Events

EventDetailDescription
bmxDiagramChange BmxDiagramChangeDetail The diagram changed. ops turn the previous diagram into this one.
bmxDiagramNodeClick BmxDiagramNodeDetail A shape was opened: clicked in a read-only diagram, or Enter on it.
bmxDiagramSelect BmxDiagramSelectDetail The selection changed.

Methods

MethodSignatureDescription
addEdge addEdge(edge: Partial<BmxDiagramEdge> & { from: BmxDiagramEnd | string; to: BmxDiagramEnd | string; }) => Promise<string | null> Connects two nodes. Resolves with the connector's id, or null if refused.
addNode addNode(node: Partial<BmxDiagramNode>) => Promise<string> Adds a node. Give at least shape; it is placed in view if x and y are left out. Resolves with its id.
applyOps applyOps(ops: readonly BmxDiagramOp[]) => Promise<void> Applies changes made somewhere else - operations from another copy's bmxDiagramChange. They are not added to this copy's undo, and raise no change event here.
arrange arrange(direction?: BmxDiagramDirection) => Promise<void> Arranges the diagram in layers, top to bottom (TB) or left to right (LR). Lanes keep their nodes.
clear clear() => Promise<void> Removes everything. Undo can bring it back.
download download(format?: BmxDiagramExportFormat, name?: string) => Promise<void> Saves the diagram as a file: svg, png, json or mermaid (.mmd).
fit fit() => Promise<void> Zooms and scrolls to show the whole diagram.
getDiagram getDiagram() => Promise<BmxDiagramData> The diagram, as JSON-ready data.
getSelection getSelection() => Promise<string[]> The ids selected.
loadMermaid loadMermaid(source: string, append?: boolean) => Promise<readonly string[]> Reads a Mermaid flowchart. With append, it goes beside what is there; otherwise it replaces it. Resolves with any lines that could not be read.
redo redo() => Promise<void>
removeItems removeItems(ids: readonly string[]) => Promise<void> Removes nodes, connectors or lanes by id. A node's connectors go with it.
reveal reveal(id: string) => Promise<void> Brings a node into view and selects it.
setDiagram setDiagram(diagram: Partial<BmxDiagramData> | string) => Promise<void> Replaces the diagram. Undo can step back from it.
setFocus setFocus(options?: FocusOptions) => Promise<void>
setSelection setSelection(ids: readonly string[]) => Promise<void> Selects by id.
toBlob toBlob(type?: "png" | "svg", scale?: number) => Promise<Blob> The diagram as a PNG or SVG file. scale multiplies the PNG's size (default 2).
toMermaid toMermaid() => Promise<string> The diagram as a Mermaid flowchart.
toSvg toSvg() => Promise<string> The diagram as a standalone SVG document.
undo undo() => Promise<void>
updateItem updateItem(id: string, patch: Record<string, unknown>) => Promise<void> Changes a node, a connector or a lane by id.
zoomTo zoomTo(zoom: number) => Promise<void> Sets the zoom (1 is actual size), about the middle of the view.

CSS shadow parts

PartDescription
outline the diagram as a list.
palette the shapes to drag in.
panel the properties of what is selected.
stage the drawing area.
toolbar the row of commands.

CSS custom properties

PropertyDescription
--bmx-diagram-background Behind the drawing.
--bmx-diagram-grid The grid's dots.
--bmx-diagram-height How tall the designer is. Default 40rem.
--bmx-diagram-line Connectors.
--bmx-diagram-selection Selection outlines, handles and guides.

<bmx-dialog>

Properties

PropertyAttributeTypeDefaultDescription
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

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

Methods

MethodSignatureDescription
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

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

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

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

Methods

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

Slots

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

CSS shadow parts

PartDescription
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

PropertyDescription
--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-form>

Properties

PropertyAttributeTypeDefaultDescription
action action string — A URL to send the answers to. Without one, the page handles bmxFormSubmit.
autosave autosave string — A name to keep a draft of the answers under in this browser, filled back in next time.
disabled disabled boolean false Turns every field off.
functions property only Record<string, BmxFormFunction> — Functions for expressions, by name: { VAT: (n) => n * 0.2 }. A property.
hideActions hide-actions boolean false Leaves out the buttons, for a page that drives the form from script.
label label string — The form's accessible name, when it has no title.
locale locale string — The language numbers and dates are shown in. The reader's, by default.
method method string 'POST' The method action is sent with.
name name string — With a name, the answers go into an enclosing <form> as JSON under it.
page page number 0 The page on show, from 0.
readonly readonly boolean false Shows the answers as text rather than as fields.
requestInit request-init RequestInit | string — Options for the request to action and to optionsUrl (headers, credentials), as a property or JSON.
schema schema BmxFormSchema | string — The form: { title, fields } or { title, pages }, as a property or JSON.
src src string — A URL to read the schema from as JSON.
strings strings Partial<BmxFormStrings> | string — Replacements for the form's own wording, as a property or JSON.
validateOn validate-on 'blur' | 'input' | 'submit' 'blur' When a field shows its problem: once it is left (blur), as it is typed in (input), or only when the form is sent (submit).
validators property only Record<string, BmxFormValidator> — The page's own checks, by field (email, or lines.qty for a column of rows). A property.
value value Record<string, unknown> | string {} The answers, as a property or JSON. Changes write back here.

Events

EventDetailDescription
bmxFormChange BmxFormChangeDetail An answer changed.
bmxFormInvalid BmxFormInvalidDetail The form was sent, or a page left, with problems.
bmxFormPageChange BmxFormPageChangeDetail Another page is on show.
bmxFormReset void The form was emptied back to its defaults.
bmxFormSubmit BmxFormSubmitDetail The form is valid and about to be sent. Cancel it to send the answers yourself.
bmxFormSubmitError BmxFormSubmitErrorDetail action refused the answers, or could not be reached.
bmxFormSubmitted BmxFormSubmittedDetail action accepted the answers.

Methods

MethodSignatureDescription
clearErrors clearErrors() => Promise<void> Clears the messages set by setErrors.
focusField focusField(path: string) => Promise<void> Moves focus to a field, by path, going to its page first.
getData getData(all?: boolean) => Promise<Record<string, unknown>> The answers: by default as they would be sent (hidden ones left out); with all, every answer kept.
getSummary getSummary() => Promise<BmxFormSummaryItem[]> The answers as a reader checks them: each field on show with its answer as text.
getValue getValue(path: string) => Promise<unknown> One answer, by path (email, lines[0].qty).
goToPage goToPage(page: number) => Promise<void> Goes to a page, from 0, without checking the one on show.
load load(url: string) => Promise<void> Reads the schema from a URL.
next next() => Promise<boolean> Checks the page on show and goes to the next one; false if the page has problems.
previous previous() => Promise<void> Goes back a page.
reportValidity reportValidity() => Promise<boolean> Checks the whole form and shows its problems; true when there are none.
reset reset() => Promise<void> Empties the form back to its defaults, on its first page.
setData setData(data: Record<string, unknown>, merge?: boolean) => Promise<void> Replaces the answers, or with merge adds to them.
setErrors setErrors(errors: Record<string, string>) => Promise<void> Shows messages against fields, by path - a server's answer, typically. They clear as each field is changed.
setValue setValue(path: string, value: unknown) => Promise<void> Sets one answer, by path, as though it had been typed.
submit submit() => Promise<boolean> Checks the form and, when it passes, sends it: bmxFormSubmit, then action if there is one.
toFormData toFormData() => Promise<FormData> The answers to send, as FormData (lines[0][qty]), files included.
validate validate(page?: number) => Promise<BmxFormError[]> The problems, without showing them: the whole form's, or one page's. Waits for the page's own validators.

CSS shadow parts

PartDescription
actions the buttons under the form.
content text from the schema.
error a message under a field the form draws itself.
error-summary the list of problems shown when the form is sent.
field the cell around one field.
form the form itself.
header the title and description.
notice the "restored" notice and the sending error.
output a worked-out value.
page the fields of the page on show.
progress the steps of a form in pages.
repeat a repeating section.
review the answers on the "check your answers" step.
row one row of a repeating section.
row-label a row's label.
section a section.
signature a signature box.
step one step. Also step-current, step-done.
success what shows once the form is sent.

CSS custom properties

PropertyDescription
--bmx-form-accent The progress steps and links.
--bmx-form-border Lines around sections, rows and the summary.
--bmx-form-error-color Messages the form draws itself, and the summary's edge.
--bmx-form-gap The space between fields.
--bmx-form-max-width The widest the form grows.
--bmx-form-output-background Behind a worked-out value.
--bmx-form-radius Corners of sections, rows and boxes.
--bmx-form-section-background Behind a section and a repeating row.

<bmx-form-designer>

Properties

PropertyAttributeTypeDefaultDescription
functions property only Record<string, BmxFormFunction> — Functions the form's expressions may call, so the designer knows them and the preview runs them. A property.
label label string — The designer's accessible name.
locale locale string — The language the preview shows numbers and dates in.
readonly readonly boolean false Shows the form without letting it be changed.
schema schema BmxFormSchema | string {} The form being designed, as a property or JSON. Changes write back here.
strings strings Partial<BmxFormDesignerStrings> | string — Replacements for the designer's own wording, as a property or JSON.
templates templates boolean true Offers the templates in the toolbar.
view view BmxFormDesignerView 'design' design, preview or json.

Events

EventDetailDescription
bmxFormDesignerChange BmxFormDesignerChangeDetail The form changed.
bmxFormDesignerSelect BmxFormDesignerSelectDetail Another field was chosen.

Methods

MethodSignatureDescription
addField addField(type: BmxFormFieldType, path?: number[]) => Promise<number[]> Adds a field of a type: after the chosen field, or at a place ([page, index]).
downloadJSON downloadJSON(fileName?: string) => Promise<void> Saves the form as a JSON file through the browser's download.
getProblems getProblems() => Promise<BmxFormDesignProblem[]> What is wrong with the form.
getSchema getSchema() => Promise<BmxFormSchema> The form as it now is.
loadTemplate loadTemplate(id: string) => Promise<boolean> Replaces the form with a template, by id: blank, contact, registration, order or survey.
redo redo() => Promise<boolean>
removeField removeField(path?: number[]) => Promise<void> Removes a field (the chosen one, by default).
selectField selectField(path: number[] | null) => Promise<void> Chooses a field, by place, or none.
setFocus setFocus() => Promise<void> Moves focus to the chosen field, or the first.
setSchema setSchema(schema: BmxFormSchema) => Promise<void> Replaces the form (an undo step).
undo undo() => Promise<boolean>

CSS shadow parts

PartDescription
canvas the page being designed.
card one field on the canvas. Also card-selected, card-problem.
drop-marker where a dragged field will land.
inspector the properties panel.
json the JSON view.
page-tabs the pages of a form in steps.
palette the list of field types.
palette-item one type in it.
preview the preview of the form.
toolbar the bar across the top.

CSS custom properties

PropertyDescription
--bmx-form-designer-accent The chosen card, the drop marker and active tabs.
--bmx-form-designer-border Lines between the panels and around cards.
--bmx-form-designer-canvas-background Behind the page being designed.
--bmx-form-designer-height How tall the designer is.
--bmx-form-designer-panel-background The palette and properties panels.
--bmx-form-designer-paper-background The page itself.

<bmx-formula-bar>

Properties

PropertyAttributeTypeDefaultDescription
actions actions boolean true Show the cancel, enter and insert-function buttons.
allowInvalid allow-invalid boolean false Enter formulas even when they do not read (the cell then shows #NAME?). By default Enter refuses them.
autocomplete autocomplete boolean true Suggest functions, names and table columns while typing.
cell cell string — The cell it edits in the engine: B4 or Sheet2!B4.
disabled disabled boolean false
engine engine BmxFormulaBarEngine — The engine to edit: a bmx-formula-engine or a grid in spreadsheet mode (its id, a selector or the element), or a BmxFormulaWorkbook.
expanded expanded boolean false Show the formula over several lines (it also grows on its own to maxRows).
hints hints boolean true Show the arguments of the function being typed.
label label string — Its accessible name.
locale locale string — A BCP 47 locale for the separators, when not bound to an engine.
maxRows max-rows number 6 The most lines the bar grows to before it scrolls.
nameBox name-box boolean true Show the name box.
placeholder placeholder string —
readonly readonly boolean false
referenceColors reference-colors boolean true Draw each reference in its own colour.
strings strings Partial<BmxFormulaBarStrings> | string — Every word it shows, as a property or JSON.
value value string '' The text, when not bound to an engine (or the bound cell's formula, read back).

Events

EventDetailDescription
bmxFormulaCancel { value: string; }
bmxFormulaCommit BmxFormulaCommitDetail
bmxFormulaInput BmxFormulaInputDetail
bmxFormulaNavigate BmxFormulaNavigateDetail
bmxFormulaReferences BmxFormulaReferencesDetail

Methods

MethodSignatureDescription
cancel cancel() => Promise<void> Abandons the edit and shows the cell's (or value's) text again.
commit commit(move?: "down" | "right" | "none") => Promise<void> Enters the formula: writes it to the bound cell, or sets value, and fires bmxFormulaCommit.
getValue getValue() => Promise<string> The text being edited (or shown).
insertReference insertReference(address: string) => Promise<void> Inserts a reference at the caret - or replaces the reference the caret is on - as a grid does when cells are clicked while a formula is being typed.
insertText insertText(text: string) => Promise<void> Inserts text at the caret, replacing any selection.
openFunctionPicker openFunctionPicker() => Promise<void> Opens the function picker.
setFocus setFocus() => Promise<void> Moves focus into the editor.

CSS shadow parts

PartDescription
actions the cancel, enter and function buttons.
bar the whole bar.
editor the editing area.
hint the argument hint.
input the text area typed into.
name-box the name box.
picker the function picker dialog.
problem the line saying what is wrong with the formula.
suggestions the autocomplete list.

CSS custom properties

PropertyDescription
--bmx-formula-bar-background Behind the bar.
--bmx-formula-bar-border The bar's border colour.
--bmx-formula-bar-font The editor's font. Default: the monospace token.
--bmx-formula-bar-font-size The editor's font size.
--bmx-formula-bar-name-width The name box's width. Default 7rem.
--bmx-formula-bar-radius The bar's corners.
--bmx-formula-error The colour of error values and of a fault's underline.
--bmx-formula-function The colour of function names.
--bmx-formula-number The colour of numbers.
--bmx-formula-ref-1 The colour of the first reference in a formula (and so on to 8).
--bmx-formula-ref-2 The second reference's colour.
--bmx-formula-ref-3 The third reference's colour.
--bmx-formula-ref-4 The fourth reference's colour.
--bmx-formula-ref-5 The fifth reference's colour.
--bmx-formula-ref-6 The sixth reference's colour.
--bmx-formula-ref-7 The seventh reference's colour.
--bmx-formula-ref-8 The eighth reference's colour.
--bmx-formula-string The colour of text in quotes.

<bmx-formula-engine>

Properties

PropertyAttributeTypeDefaultDescription
bind bind string — Wires up data-bmx-cell and data-bmx-formula elements inside the element this selector finds (or document). Elements naming another engine with data-bmx-engine are left to it.
calculation calculation 'automatic' | 'manual' 'automatic' automatic recalculates on every change; manual waits for recalculate().
dateSystem date-system 1900 | 1904 1900 The date system: 1900 (default) or 1904.
functions property only Record<string, BmxFormulaCustomFunction> — Functions of your own, by name. Set from script: a function cannot travel in an attribute.
iterative iterative boolean false Iterate circular references until they settle, rather than reporting #CYCLE!.
locale locale string — A BCP 47 locale: decides the formula separators, how typed numbers and dates are read, and month names.
maxChange max-change number 0.001 With iterative: stop when no value moves by more than this.
maxIterations max-iterations number 100 With iterative: the most rounds of iteration.
names names BmxFormulaNameData[] | string — Named ranges and named formulas: [{ name, formula, sheet? }].
requestInit request-init RequestInit | string — Options for the src request (headers, credentials), as a property or JSON.
sheets sheets BmxFormulaSheetData[] | string — The sheets: [{ name, cells, records?, formats? }], as a property or JSON.
src src string — A URL to load the workbook from: JSON in the shape toJSON writes, or an Excel file (.xlsx). Your server, your data.
tables tables BmxFormulaTableData[] | string — Tables for structured references: [{ name, sheet, range }].
undoLimit undo-limit number 100 How many changes undo() can step back through.
workbook property only BmxFormulaWorkbook | BmxFormulaRemoteWorkbook | null null The workbook: the full calculation API, synchronously. Read it to work with the engine from script, or assign a BmxFormulaWorkbook of your own to have the element (and anything bound to it) use that instead. With worker, it is a BmxFormulaRemoteWorkbook: reads answer at once from its mirror, changes answer with promises.
worker worker string | Worker — Calculates on a Web Worker: the URL of a module worker script that calls serveFormulaWorker() from bmx-formulas.mjs (two lines; see that module), or a Worker set from script, which the element then owns. The page stays responsive while the worker loads and recalculates, and values are read from a mirror kept here, so bound elements and formula bars work as before. Functions of your own are given to the worker, not functions. A Worker given here stays the page's to end.

Events

EventDetailDescription
bmxFormulaChange BmxFormulaChangeEvent Recalculation finished: the cells that changed, and what the calculation did.
bmxFormulaError BmxFormulaEngineErrorDetail The workbook could not be loaded or read.
bmxFormulaReady BmxFormulaReadyDetail The workbook is loaded and calculated.

Methods

MethodSignatureDescription
createWorkbook createWorkbook(data?: BmxFormulaWorkbookData, options?: BmxFormulaWorkbookOptions) => Promise<BmxFormulaWorkbook> A new, independent workbook (not bound to this element): for calculations that need no element of their own.
defineName defineName(name: string, formula: string, sheet?: string) => Promise<void> Defines or redefines a name.
downloadXlsx downloadXlsx(fileName?: string) => Promise<void> Saves the workbook as an Excel file through the browser's download.
enterText enterText(address: string, text: string) => Promise<void> Sets a cell from text as a person types it: numbers, dates and percentages are read in the engine's locale.
evaluate evaluate(formula: string) => Promise<BmxFormulaValue | BmxFormulaValue[][]> Works out a formula without storing it.
getText getText(address: string, format?: string) => Promise<string> A cell's value as text, in its number format or the one given.
getValue getValue(address: string) => Promise<BmxFormulaValue> The value of a cell. An error value arrives as a BmxFormulaError with its code and message.
getValues getValues(range: string) => Promise<BmxFormulaValue[][]> The values of a range as rows.
getWorkbook getWorkbook() => Promise<BmxFormulaWorkbook | BmxFormulaRemoteWorkbook | null> The workbook itself, for the full API (also the workbook property).
load load(url: string) => Promise<void> Loads the workbook from a URL: JSON in the shape toJSON writes, or an Excel file (.xlsx), told apart by the response's content type or the URL's extension.
loadXlsx loadXlsx(source: Blob | ArrayBuffer | Uint8Array | string) => Promise<void> Loads an Excel file (.xlsx): from a File a reader chose, a Blob, its bytes, or a URL. Cells, formulas, number formats, names, tables, the date system and iterative calculation come across.
recalculate recalculate() => Promise<BmxFormulaTelemetry | null> Recalculates every formula (in manual mode, runs what is waiting).
redo redo() => Promise<boolean>
registerFunction registerFunction(name: string, def: BmxFormulaCustomFunction) => Promise<void> Adds a function of your own: engine.registerFunction('VAT', { fn: x => x * 0.2 }).
setCell setCell(address: string, input: BmxFormulaInput) => Promise<void> Sets one cell: a value, or text starting with = for a formula.
setCells setCells(entries: Record<string, BmxFormulaInput>) => Promise<void> Sets several cells, recalculating once: { "A1": 1, "B1": "=A1*2" }.
setData setData(data: BmxFormulaWorkbookData) => Promise<void> Replaces the workbook with JSON.
toJSON toJSON(values?: boolean) => Promise<BmxFormulaWorkbookData> The whole workbook as JSON; with values, each sheet's calculated values as well.
toXlsx toXlsx() => Promise<Blob> The workbook as an Excel file: formulas, their values, number formats, names and tables.
undo undo() => Promise<boolean>

<bmx-gantt>

Properties

PropertyAttributeTypeDefaultDescription
applyChanges apply-changes boolean true Whether an edit is applied by the chart itself. On by default, so a plain page works with no script; turn it off to own the lists entirely.
canChange property only (detail: BmxGanttTaskChangeDetail) => boolean — Whether a change may be made, asked while a drag moves and before any edit is applied. A function, so it is set from script. js gantt.canChange = ({ edits }) => edits.every(e => !e.edit.start?.endsWith('-25'));
columns columns (BmxGanttColumn | BmxGanttColumnKey)[] | string [...DEFAULT_COLUMNS] The task-list columns, in order: columns="wbs,name,start,duration", or objects with a label and width from script.
editable editable boolean false Lets the reader drag bars, draw links and edit cells.
firstDayOfWeek first-day-of-week number 1 The first day of the week in the headers, 0 for Sunday.
gridWidth grid-width number 460 Width of the task list in pixels. The reader can drag the divider.
holidays holidays string[] | string [] Dates that are not worked, YYYY-MM-DD: holidays="2026-12-25,2026-12-28".
label label string — What the plan is called. Without one it is announced as "Project plan".
links links BmxTaskLink[] | string [] The links between tasks.
locale locale string — The locale dates are written in. Defaults to the page's.
projectStart project-start string — The first day work can happen, YYYY-MM-DD. Defaults to the earliest task start.
rowHeight row-height number 36 Row height in pixels. A layout input: the timeline and the list are placed from it.
showBaselines show-baselines boolean false Draws each task's baseline under its bar.
showCriticalPath show-critical-path boolean true Draws the critical path in the critical colour.
showLinks show-links boolean true Draws the links.
showToday show-today boolean true Draws a line at today.
tasks tasks BmxTask[] | string [] The tasks, as a flat list with parent references.
today today string — Which day is today, YYYY-MM-DD. Defaults to the reader's date.
toolbar toolbar boolean true Shows the zoom and "today" buttons above the chart.
workingDays working-days number[] | string [1, 2, 3, 4, 5] Days of the week that are worked, 0 for Sunday: working-days="1,2,3,4,5".
zoom zoom BmxGanttZoom 'week' How much time the timeline shows: day, week, month, quarter or year.

Events

EventDetailDescription
bmxLinkChange BmxGanttLinkChangeDetail Links are about to change. Cancelable.
bmxSchedule BmxGanttScheduleDetail The plan was scheduled, with anything in it that could not be used.
bmxSelect BmxGanttSelectDetail A task was chosen.
bmxTaskChange BmxGanttTaskChangeDetail Tasks are about to change. Cancelable.
bmxToggle BmxGanttToggleDetail A summary task was opened or closed.
bmxZoomChange { readonly zoom: BmxGanttZoom; } The zoom changed.

Methods

MethodSignatureDescription
collapseAll collapseAll() => Promise<void> Closes every summary.
expandAll expandAll() => Promise<void> Opens every summary.
exportPng exportPng() => Promise<Blob | null> The whole plan as a PNG image, at twice the pixel density for print.
exportSvg exportSvg() => Promise<string> The whole plan - every row, open or not - as a standalone SVG document.
getSchedule getSchedule() => Promise<BmxSchedule> The plan as scheduled: dates, float, the critical path and any problems.
print print() => Promise<void> Prints the whole plan. The chart on screen shows only what is in view, so printing the page would print a window of it; this prints every row.
scrollToTask scrollToTask(id: string) => Promise<void> Scrolls a task into view in both panes, opening its summaries, and focuses its row.
scrollToToday scrollToToday() => Promise<void> Scrolls the timeline to today.
toggle toggle(id: string, expanded?: boolean) => Promise<void> Opens or closes one summary.
zoomIn zoomIn() => Promise<void> Shows less time, in more detail.
zoomOut zoomOut() => Promise<void> Shows more time, in less detail.
zoomToFit zoomToFit() => Promise<void> Picks the finest zoom that shows the whole plan without scrolling sideways.

Slots

SlotDescription
empty what to draw when there are no tasks.
toolbar-end extra controls after the built-in zoom buttons.

CSS shadow parts

PartDescription
bar-label
baseline
cell-editor
chart
empty
frame
grid
grid-body
grid-header
link-draft
link-handle
link-remove
links
non-working
plot
progress
progress-handle
resize-handle
row-band
side-label
splitter
tick
tick-major
timeline-body
timeline-header
today
toggle
toolbar
toolbar-button
zoom-name

CSS custom properties

PropertyDescription
--bmx-gantt-bar-background A task bar's unfinished part.
--bmx-gantt-bar-color Text on a bar.
--bmx-gantt-bar-height How much of the row a bar fills, as a length.
--bmx-gantt-bar-progress A task bar's finished part.
--bmx-gantt-bar-radius A task bar's corners.
--bmx-gantt-baseline-color The baseline under a bar.
--bmx-gantt-border The lines between rows, columns and header ticks.
--bmx-gantt-critical-background A critical bar's unfinished part.
--bmx-gantt-critical-progress A critical bar's finished part, and critical links.
--bmx-gantt-grid-width Width of the task list. Written by the component from grid-width.
--bmx-gantt-header-background The header rows' fill.
--bmx-gantt-header-color The header text.
--bmx-gantt-height How tall the chart is, header included.
--bmx-gantt-link-color The links between bars.
--bmx-gantt-non-working-background Weekends and holidays behind the bars.
--bmx-gantt-row-height Height of a row. Written by the component from row-height.
--bmx-gantt-row-hover A row under the pointer.
--bmx-gantt-row-selected The chosen row, in the list and across the timeline.
--bmx-gantt-summary-color A summary bar and a milestone.
--bmx-gantt-today-color The line at today. @part toolbar - the zoom and "today" buttons. @part toolbar-button - one of them. @part zoom-name - the current zoom's name. @part frame - the task list, the divider and the timeline together. @part grid - the task list (role="treegrid"). @part grid-header - the list's header row. @part grid-body - the list's scrolling body. @part column-header - one heading. Also column-header-<key>. @part row - one task's row. Also row-summary, row-selected. @part cell - one cell. Also cell-<key>. @part cell-editor - the input while a cell is edited. @part toggle - the arrow that opens a summary. @part name - a task's name in the list. Also name-milestone. @part splitter - the divider between the list and the timeline. @part chart - the timeline side. @part timeline-header - the two rows of dates. @part tick - one date in them. Also tick-major, tick-minor, tick-non-working, tick-today. @part timeline-body - the scrolling timeline. @part plot - the drawing surface inside it. @part non-working - a shaded weekend or holiday. @part row-band - a row's stripe across the timeline. @part bar - one bar. Also bar-task, bar-summary, bar-milestone, bar-critical, bar-<category>. @part track - a task bar's unfinished part. @part summary-track - a summary bar. @part progress - a task bar's finished part. @part bar-label - a task's name on its bar. @part side-label - a task's name beside a bar too short to hold it. @part baseline - the baseline under a bar. @part resize-handle - the grip on a bar's end, when editable. @part progress-handle - the grip at the end of the finished part. @part link-handle - the dot a link is drawn from. @part links - the SVG layer of links. @part link - one link. Also link-critical. @part link-draft - the link being drawn. @part link-remove - the button that removes the chosen link. @part today - the line at today. @part empty - what is drawn when there are no tasks.

<bmx-image-editor>

Properties

PropertyAttributeTypeDefaultDescription
actions actions readonly BmxImageAction[] | string 'reset,download' The buttons in the footer: any of reset, cancel, apply, download. editFile adds cancel and apply while it waits.
aspect aspect string — The crop shape at the start ("1:1"). With lock-aspect, the only one.
aspectRatios aspect-ratios readonly string[] | string 'free,original,1:1,4:5,3:2,4:3,16:9' The crop shapes offered: "free", "original", or ratios such as "16:9".
background background string '#ffffff' Painted behind transparent parts when saving as JPEG.
cropShape crop-shape 'rect' | 'circle' 'rect' Show the crop as a circle, and save the picture round (transparent outside it in PNG and WebP).
disabled disabled boolean false
edits edits Partial<BmxImageEdits> | string — Edits to apply to the picture when it opens (JSON in markup). Kept up to date as the picture is edited.
fileName file-name string — The saved file's name. Default: the original's, with the new format's extension.
fontFamily font-family string 'system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif' The font text marks are drawn in, as CSS font-family.
label label string — What the editor is, for screen readers.
lockAspect lock-aspect boolean false Keep the crop to aspect and offer no other shape: an avatar, a banner.
maxHeight max-height number — The tallest the saved picture may be.
maxPixels max-pixels number 16_777_216 The most pixels the saved picture may have. Default 16.7 million, the most some phones can draw.
maxWidth max-width number — The widest the saved picture may be.
name name string — The form field name. The edited picture is submitted as a file.
palette palette readonly string[] | string ['#e03131', '#f08c00', '#ffd43b', '#2f9e44', '#1971c2', '#7048e8', '#111111', '#ffffff'] Colours offered for marks: a list, or comma-separated in markup.
quality quality number 0.9 Quality for JPEG and WebP, from 0 to 1.
required required boolean false A picture must be opened before the form can be sent.
src src string — The picture to open: a URL (a picture from another site must allow CORS), a data URL or an object URL. Or call loadImage with a file.
strings strings Partial<BmxImageEditorStrings> | string — Words the editor shows or says: any of BmxImageEditorStrings. JSON in markup.
tool tool BmxImageTool — The tool open at the start.
tools tools readonly BmxImageTool[] | string ['crop', 'adjust', 'filter', 'annotate', 'redact', 'resize'] The tools offered, in order: any of crop, adjust, filter, annotate, redact, resize. A list, or comma-separated in markup.
type type string — The format saved: image/jpeg, image/png or image/webp. Default: the original's, or PNG.

Events

EventDetailDescription
bmxImageApply BmxImageFileDetail The reader pressed Done: the finished file.
bmxImageCancel void The reader pressed Cancel.
bmxImageEdit BmxImageEditDetail The edits changed.
bmxImageError BmxImageErrorDetail A picture could not be opened or saved.
bmxImageExport BmxImageFileDetail The picture was saved: downloaded, or made into a file or blob.
bmxImageLoad BmxImageLoadDetail A picture opened. metadata says what it carried besides pixels.
bmxImageToolChange BmxImageToolDetail The reader chose another tool.

Methods

MethodSignatureDescription
cleanFile cleanFile(file: Blob, name?: string) => Promise<File> Takes the location, camera and other details out of any JPEG, PNG or WebP file, without changing a pixel or compressing it again. Needs no picture open.
clear clear() => Promise<void> Closes the picture.
download download(name?: string, options?: BmxImageExportOptions) => Promise<void> Saves the edited picture to the reader's downloads.
editFile editFile(file: Blob, name?: string) => Promise<File | null> Opens a file to edit and waits: resolves with the edited file when the reader presses Done, or null when they press Cancel. For an upload field: upload.prepareFile = file => editor.editFile(file).
flip flip(axis?: "horizontal" | "vertical") => Promise<void> Mirrors the picture.
getEdits getEdits() => Promise<BmxImageEdits> The edits, as JSON-ready data.
getMetadata getMetadata() => Promise<BmxImageMetadata | null> What the open picture carried besides pixels (location, camera, owner), or null.
loadImage loadImage(source: BmxImageSource, name?: string) => Promise<void> Opens a picture: a file, a blob, a URL, an <img>, a canvas, an ImageBitmap or ImageData. Resolves when it is shown.
redo redo() => Promise<void>
reset reset() => Promise<void> Back to the picture as it opened. Undo can step back from it.
rotate rotate(direction?: "left" | "right") => Promise<void> Turns the picture a quarter.
setEdits setEdits(edits: Partial<BmxImageEdits> | string) => Promise<void> Replaces the edits, from data or JSON. Undo can step back from it.
setFocus setFocus(options?: FocusOptions) => Promise<void>
setTool setTool(tool: BmxImageTool) => Promise<void> Opens a tool.
toBlob toBlob(options?: BmxImageExportOptions) => Promise<Blob> The edited picture as a Blob.
toDataURL toDataURL(options?: BmxImageExportOptions) => Promise<string> The edited picture as a data URL.
toFile toFile(name?: string, options?: BmxImageExportOptions) => Promise<File> The edited picture as a File.
undo undo() => Promise<void>

CSS shadow parts

PartDescription
empty what shows before a picture is opened.
footer the size, the privacy note and the actions.
panel the current tool's settings.
stage the area the picture is shown in.
toolbar the row of tools and commands.

CSS custom properties

PropertyDescription
--bmx-image-editor-crop The crop's edge and handles.
--bmx-image-editor-height How tall the editor is. Default 36rem.
--bmx-image-editor-selection The outline and handles of the selected mark.
--bmx-image-editor-shade Over the part the crop leaves out.
--bmx-image-editor-stage Behind the picture.

<bmx-infinite-canvas>

Properties

PropertyAttributeTypeDefaultDescription
changeBatch change-batch number 0 Gather changes for this many milliseconds into one bmxCanvasStateChange. 0 sends each at once.
channel channel string — Share this board with every other canvas in the same browser that has the same channel - other tabs and windows of the site - with no server. For users on other machines, pass a relay to joinRoom().
clientId client-id string — This copy's id in a shared session: part of every change it makes. Read once, when the element loads.
cursorThrottle cursor-throttle number 50 bmxCursorMove at most this often.
edgeRoute edge-route BmxCanvasRoute 'curved' How new connectors run.
edges edges BmxCanvasEdge[] | string [] The connectors. Setting the list makes the board hold exactly these.
fitOnLoad fit-on-load boolean true Frame the board when it loads.
follow follow string — Follow another user's view: their peer id. Panning or zooming yourself stops following.
grid grid 'dots' | 'lines' | 'none' 'dots' The background grid.
gridSize grid-size number 24 Grid spacing in world units.
guides guides boolean true Line dragged items up with their neighbours, and show guides.
label label string — The accessible name. Default: "Canvas".
lodThreshold lod-threshold number 500 More items in view than this and the board is painted rather than built from DOM.
lodZoom lod-zoom number 0.4 Below this zoom the board is painted rather than built from DOM.
maxImageBytes max-image-bytes number 2_000_000 Images dropped or pasted larger than this, in bytes, are refused unless uploadImage is set.
maxZoom max-zoom number 8
minZoom min-zoom number 0.05
minimap minimap boolean true Show the minimap.
moveThrottle move-throttle number 50 bmxNodeMove at most this often during a drag, in milliseconds.
nodes nodes BmxCanvasNode[] | string [] The nodes. Setting the list makes the board hold exactly these, with the fewest changes; JSON in markup.
noteColor note-color string 'yellow' The colour of new notes and shapes: yellow orange pink violet blue teal green grey, or any CSS colour.
peers peers BmxCanvasPeer[] | string [] Other users on the board.
penColor pen-color string '' The pen's colour: a palette name or any CSS colour. Empty draws in the theme's text colour.
penWidth pen-width number 3 The pen's width in world units. The highlighter is five times as wide.
readonly readonly boolean false View only: pan, zoom and select, but change nothing.
shapeKind shape-kind BmxCanvasShapeKind 'rounded' The outline the shape tool draws.
snapToGrid snap-to-grid boolean false Snap moved, resized and new items to the grid. Alt held while dragging turns it off.
tool tool BmxCanvasTool 'select' What the pointer does.
toolbar toolbar boolean true Show the toolbar.
uploadImage property only (file: File) => Promise<string> — Turns a dropped or pasted image file into an address the node will show, such as the URL of your upload. Without it, images are kept in the board as data URLs. Set from script; markup cannot hold a function.
userColor user-color string — Your colour, shown to the others in a room: any CSS colour.
userName user-name string — Your name, shown to the others in a room.
viewportThrottle viewport-throttle number 100 bmxViewportChange at most this often.
wheel wheel 'auto' | 'pan' | 'zoom' 'auto' What the mouse wheel does: auto zooms with a wheel and pans with a trackpad; Ctrl or Cmd always zooms.
zoomControls zoom-controls boolean true Show the zoom buttons.

Events

EventDetailDescription
bmxCanvasStateChange BmxCanvasStateChangeDetail The board changed here: send detail.ops to the other copies.
bmxCursorMove BmxCanvasCursorDetail The pointer moved over the board, or left it.
bmxFileDrop BmxCanvasFileDropDetail Files were dropped or pasted. Cancel it to handle them yourself; otherwise images are added.
bmxNodeActivate BmxCanvasActivateDetail A node with nothing to edit - an image, embedded content - was opened.
bmxNodeMove BmxCanvasNodeMoveDetail Nodes are being dragged or resized.
bmxPeersChange BmxCanvasPeersChangeDetail The users in the room changed.
bmxSelectionChange BmxCanvasSelectionDetail The selection changed.
bmxToolChange BmxCanvasToolDetail The tool changed.
bmxViewportChange BmxCanvasViewportDetail The view moved or zoomed.

Methods

MethodSignatureDescription
addEdges addEdges(edges: readonly Partial<BmxCanvasEdge>[] | Partial<BmxCanvasEdge>) => Promise<BmxCanvasEdge[]>
addImage addImage(file: Blob, at?: BmxCanvasPoint) => Promise<BmxCanvasNode | null> Adds an image from a file or blob, centred on a world point or the view.
addNodes addNodes(nodes: readonly Partial<BmxCanvasNode>[] | Partial<BmxCanvasNode>) => Promise<BmxCanvasNode[]> Adds nodes; returns them as stored, with ids given to those without.
align align(how: BmxCanvasAlign, ids?: readonly string[]) => Promise<void> Lines nodes up: the selection when none are given.
applyRemote applyRemote(ops: readonly BmxCanvasOp[] | BmxCanvasOp) => Promise<number> Applies changes from another copy of the board, as bmxCanvasStateChange or bmxNodeMove gave them there. Returns how many took effect.
bringToFront bringToFront(ids?: readonly string[]) => Promise<void> Brings nodes to the front: the selection when none are given.
centerOn centerOn(id: string, animate?: boolean) => Promise<boolean> Brings a node to the centre of the view, zooming in if it is too small to read.
distribute distribute(axis: "horizontal" | "vertical", ids?: readonly string[]) => Promise<void> Spaces three or more nodes evenly: the selection when none are given.
exportJson exportJson(options?: BmxCanvasExportOptions) => Promise<string> The board as JSON text: the snapshot.
exportPng exportPng(options?: BmxCanvasExportOptions) => Promise<Blob> The board, or the selection, as a PNG image. Images from other sites appear only if they allow it (CORS).
exportSvg exportSvg(options?: BmxCanvasExportOptions) => Promise<string> The board, or the selection, as an SVG document.
find find(text: string) => Promise<string[]> The nodes whose text contains text, in reading order.
followPeer followPeer(id: string | null) => Promise<void> Follows another user's view, by their peer id; null stops.
getNode getNode(id: string) => Promise<BmxCanvasNode | null> A copy of one node.
getSelection getSelection() => Promise<BmxCanvasSelectionDetail>
getSnapshot getSnapshot() => Promise<BmxCanvasSnapshot> The board as plain data, to save.
getSyncState getSyncState() => Promise<BmxCanvasSyncState> The board with every change's stamp: what a client joining late merges with mergeSyncState().
getViewport getViewport() => Promise<BmxCanvasViewportDetail>
group group(ids?: readonly string[]) => Promise<string | null> Groups nodes, so they are selected and moved together: the selection when none are given. Returns the group id.
insertTemplate insertTemplate(name: BmxCanvasTemplate) => Promise<string[]> Adds a ready-made board - retro, kanban, swot, flowchart or mindmap - where the view is, and shows it. Returns the new ids.
joinRoom joinRoom(room: BmxCanvasTransport | string) => Promise<boolean> Shares the board through a room: a channel name, for the other tabs of this browser, or a transport - { send(text), subscribe(listener) } - over a relay that forwards each message to the others. Changes, drags, pointers, selections and views are exchanged, and a copy that joins late is brought up to date. Returns false if the transport is not available.
leaveRoom leaveRoom() => Promise<void> Leaves the room, telling the others.
loadSnapshot loadSnapshot(snapshot: BmxCanvasSnapshot) => Promise<void> Replaces the board. Sends nothing and clears the undo history.
mergeSyncState mergeSyncState(state: BmxCanvasSyncState) => Promise<boolean> Merges another copy's sync state. Returns whether anything changed.
redo redo() => Promise<boolean>
removeEdges removeEdges(ids: readonly string[] | string) => Promise<void>
removeNodes removeNodes(ids: readonly string[] | string) => Promise<void> Removes nodes, and the connectors that end on them.
rotate rotate(degrees: number, ids?: readonly string[]) => Promise<void> Turns nodes by degrees, clockwise, about the centre of the box around them: the selection when none are given. Frames and locked nodes stay as they are. To set a node's angle outright, update its rotation.
screenToWorld screenToWorld(clientX: number, clientY: number) => Promise<BmxCanvasPoint> A point in the page (clientX, clientY) in world units.
select select(ids: readonly string[] | string) => Promise<void> Selects nodes and connectors by id; an empty list clears the selection.
sendToBack sendToBack(ids?: readonly string[]) => Promise<void> Sends nodes to the back: the selection when none are given.
setFocus setFocus() => Promise<void> Focuses the board.
setViewport setViewport(viewport: Partial<BmxCanvasCamera>, animate?: boolean) => Promise<void> Moves the view: x and y are the world point for the top-left corner.
tidy tidy(ids?: readonly string[]) => Promise<void> Lays nodes out in a tidy grid: the selection when none are given.
undo undo() => Promise<boolean>
ungroup ungroup(ids?: readonly string[]) => Promise<void> Takes nodes out of their groups: the selection when none are given.
updateEdges updateEdges(updates: readonly (Partial<BmxCanvasEdge> & { id: string; })[] | (Partial<BmxCanvasEdge> & { id: string; })) => Promise<void>
updateNodes updateNodes(updates: readonly (Partial<BmxCanvasNode> & { id: string; })[] | (Partial<BmxCanvasNode> & { id: string; })) => Promise<void> Changes nodes: each entry names the node by id and carries the fields to change.
vote vote(id: string, delta?: number) => Promise<{ total: number; mine: number; } | null> Adds this user's vote to a node, or takes one away with a negative delta.
worldToScreen worldToScreen(x: number, y: number) => Promise<BmxCanvasPoint> A world point as a point in the page.
zoomIn zoomIn() => Promise<void>
zoomOut zoomOut() => Promise<void>
zoomTo zoomTo(zoom: number, animate?: boolean) => Promise<void> Zooms about the centre of the view.
zoomToFit zoomToFit(ids?: readonly string[], animate?: boolean) => Promise<void> Frames the whole board, or the nodes given.

Slots

SlotDescription
(named) an html node's content: give the element the node's slot name.
toolbar-end extra controls at the end of the toolbar.

CSS shadow parts

PartDescription
arrange-select
context-bar
context-button
drawbar
edge-end
edges
far-layer
following
handle
minimap
port
search
search-count
search-input
selection
shape-select
swatch
templates-item
templates-menu
tool
toolbar
turn-handle
viewport
world
zoom-button
zoom-controls

CSS custom properties

PropertyDescription
--bmx-infinite-canvas-background Behind the board.
--bmx-infinite-canvas-blue The blue note.
--bmx-infinite-canvas-blue-ink Blue lines.
--bmx-infinite-canvas-edge Connectors without a colour of their own.
--bmx-infinite-canvas-frame Inside a frame.
--bmx-infinite-canvas-green The green note.
--bmx-infinite-canvas-green-ink Green lines.
--bmx-infinite-canvas-grey The grey note.
--bmx-infinite-canvas-grey-ink Grey lines.
--bmx-infinite-canvas-grid The grid's dots or lines.
--bmx-infinite-canvas-height How tall the canvas is.
--bmx-infinite-canvas-laser The laser pointer's trail. @part viewport - the board: pan, zoom and everything drawn on it. @part world - the layer that moves and zooms. @part edges - the connectors. @part far-layer - the painted board, zoomed far out. @part selection - the box around the selection. @part handle - a resize handle. @part port - a dot to drag a connector from. @part edge-end - an end of the selected connector, to drag onto another item. @part toolbar - the tools. @part tool - one tool button. @part context-bar - the bar over the selection. @part context-button - one of its buttons. @part swatch - a colour in it. @part shape-select - its shape list. @part zoom-controls - the zoom buttons. @part zoom-button - one of them. @part minimap - the overview in the corner. @part drawbar - the pen, highlighter, eraser and ink colours, while drawing. @part templates-menu - the list of templates. @part templates-item - one template in it. @part arrange-select - the Arrange list over a selection of several items. @part search - the find bar. @part search-input - its field. @part search-count - "2 of 5". @part following - the note saying whose view is being followed.
--bmx-infinite-canvas-note-text Text on notes and coloured shapes, which keep their paper colours on dark themes.
--bmx-infinite-canvas-orange The orange note.
--bmx-infinite-canvas-orange-ink Orange lines.
--bmx-infinite-canvas-pink The pink note.
--bmx-infinite-canvas-pink-ink Pink lines.
--bmx-infinite-canvas-selection Selection outlines, handles and guides.
--bmx-infinite-canvas-teal The teal note.
--bmx-infinite-canvas-teal-ink Teal lines.
--bmx-infinite-canvas-violet The violet note.
--bmx-infinite-canvas-violet-ink Violet lines.
--bmx-infinite-canvas-yellow The yellow note. Also -orange, -pink, -violet, -blue, -teal, -green and -grey.
--bmx-infinite-canvas-yellow-ink Lines and text in yellow: a shape's outline, a connector. Also -orange-ink and so on.

<bmx-input>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
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

PartDescription
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

PropertyDescription
--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-log-stream>

Properties

PropertyAttributeTypeDefaultDescription
bookmarks property only number[] [] Bookmarked line numbers.
bookmarksOnly bookmarks-only boolean false Show only the bookmarked entries.
caseSensitive case-sensitive boolean false Match the search's letter case.
columns columns string '' Lay the lines out as columns: auto, or field names separated by spaces. @time, @level and @message are the line's own. Empty shows whole lines.
context context number 0 Entries to show either side of each match.
dropFiles drop-files boolean true Open a file dropped on the viewer.
fieldsPanel fields-panel boolean false Show the fields panel: each field's commonest values, to filter by.
fileName file-name string — The name exported files are saved under.
follow follow boolean false Keep the newest line in view as lines arrive. Scrolling up turns it off.
format format BmxLogFormat 'auto' The format of the lines. auto reads it from the first lines.
label label string — The accessible name. Default: "Log".
levels levels string | readonly string[] '' Levels to show, separated by spaces: warn error fatal; none for lines with no level. Empty shows all.
lineNumbers line-numbers boolean true Show line numbers.
liveSrc live-src string — A WebSocket (ws:, wss:) or server-sent events URL to follow live.
liveType live-type 'auto' | 'websocket' | 'sse' 'auto' What liveSrc is. auto goes by the URL's scheme.
maxLines max-lines number 0 Keep at most this many lines, dropping the oldest: for live logs. 0 keeps all.
pattern pattern string — For format="pattern": a regular expression with named groups; level, time and message are understood.
query query string '' The search: words, "phrases", /regex/, field:value, -exclusions, OR.
redact redact boolean | string false Mask personal data and secrets: true for every rule, or rule names: email ip card jwt bearer aws-key secret.
redactRules property only readonly BmxLogRedactRule[] — Masking rules of your own: { name, pattern, flags?, mask? }.
regex regex boolean false Treat the search as one regular expression.
requestInit property only RequestInit — Options for fetching src: headers, credentials.
src src string — A URL to read the log from, streamed as it downloads. A .gz file is decompressed.
timeFrom time-from string | number — Show entries from this time on: an ISO date or milliseconds since 1970. Set by the timeline.
timeTo time-to string | number — Show entries before this time. Set by the timeline.
timeZone time-zone 'utc' | 'local' 'utc' Show times in UTC or in the reader's own time zone.
timeline timeline boolean true Show the timeline over the lines, when they carry times.
toolbar toolbar boolean true Show the toolbar.
wholeWord whole-word boolean false Match the search's words only as whole words.
wrap wrap boolean false Wrap long lines instead of scrolling sideways.

Events

EventDetailDescription
bmxLogBookmark BmxLogBookmarkDetail A bookmark was added or removed.
bmxLogConnection BmxLogConnectionDetail A live connection opened, dropped, is being tried again, or closed.
bmxLogFilter BmxLogFilterDetail The lines on show changed.
bmxLogLoad BmxLogLoadDetail Text arrived, or the load finished or failed.
bmxLogSelect BmxLogSelectDetail A line was chosen: clicked, or reached by the keyboard.
bmxLogStateChange BmxLogStateChangeDetail The search, levels, time range, bookmarks, columns or chosen line changed.

Methods

MethodSignatureDescription
appendLog appendLog(text: string | readonly string[]) => Promise<number> Adds text or lines, as from a live source. Text without a final line break waits for the rest.
clear clear() => Promise<void> Forgets every line.
connect connect(url: string, options?: BmxLogConnectOptions) => Promise<void> Follows a live source: a WebSocket (ws:, wss:) or a server-sent events URL. Each message is one or more lines. The connection is opened again when it drops; bmxLogConnection reports each change.
disconnect disconnect() => Promise<void> Closes the live connection. The lines already received stay.
download download(format?: BmxLogExportFormat, fileName?: string) => Promise<void> Saves the lines on show, under fileName or log.
exportAs exportAs(format?: BmxLogExportFormat) => Promise<Blob> The lines on show as a file: text, csv or json, masked as on screen.
findNext findNext() => Promise<number | null> Moves to the next match. Resolves to its line number, or null when there is none.
findPrevious findPrevious() => Promise<number | null> Moves to the previous match.
getLine getLine(lineNumber: number) => Promise<(BmxLogLine & { fields: Record<string, unknown> | null; }) | null> A line by its number, or null when it is not held.
getState getState() => Promise<string> What the reader is looking at, as a short URL-safe string: the search, levels, context, time range, bookmarks, columns and the chosen line. Keep it in a link and give it to setState() to open the same view.
getStats getStats() => Promise<BmxLogStats> Counts: lines held and shown, matches, characters, and entries per level.
load load(source: BmxLogSource) => Promise<void> Reads a log, replacing what is shown: a File or Blob (a dropped or chosen file), a URL, a Response, or a stream. Gzip is recognised and decompressed.
scrollToLine scrollToLine(lineNumber: number) => Promise<boolean> Scrolls to a line by its number, selects it, and says whether it is on show.
setState setState(state: string) => Promise<boolean> Opens a view saved by getState(). Call it once the log is loaded, so the chosen line can be found. False when the string is not a saved view.

Slots

SlotDescription
empty what to show when there are no lines.
toolbar-end extra controls at the end of the toolbar.

CSS shadow parts

PartDescription
body
button
cell
columns-head
context
details
drop-zone
empty
error
export-list
export-option
field
field-value
fields
fields-panel
fold
latest
level
level-chip
level-chip-bookmarks
level-chip-none
line-number
match
match-count
option
query-error
raw
search
search-input
status
text
timeline
timeline-chart
toolbar
viewport

CSS custom properties

PropertyDescription
--bmx-log-stream-active The chosen line.
--bmx-log-stream-ansi-0 Terminal black. -1 to -7 are red, green, yellow, blue, magenta, cyan and white; -8 to -15 their bright forms.
--bmx-log-stream-ansi-1 Terminal red.
--bmx-log-stream-ansi-10 Terminal bright green.
--bmx-log-stream-ansi-11 Terminal bright yellow.
--bmx-log-stream-ansi-12 Terminal bright blue.
--bmx-log-stream-ansi-13 Terminal bright magenta.
--bmx-log-stream-ansi-14 Terminal bright cyan.
--bmx-log-stream-ansi-15 Terminal bright white. @part toolbar - the controls above the lines. @part button - a toolbar button. @part search - the search group. @part search-input - the search field. @part option - the match case, whole word and regular expression toggles. @part match-count - "3 of 12". @part query-error - what is wrong with the search. @part context - the context control. @part export-list - the list of file types under Export. @part export-option - one of them. @part level-chip - a level's toggle. Also level-chip-error and so on, and level-chip-bookmarks. @part timeline - the timeline over the lines. @part timeline-chart - its bars, which choose a stretch of time. @part fields-panel - the fields panel. @part field - one field in it. @part field-value - one of its values, which filters by it. @part columns-head - the column titles, in the column layout. @part cell - one column of a line. @part body - the lines and what lies over them. @part viewport - the scrolling list of lines. @part line-number - a line's number. @part level - a line's level mark. @part fold - the button that folds an entry's following lines. @part text - a line's text. @part match - a search match. @part latest - the "new lines" button while not following. @part drop-zone - shown while a file is dragged over. @part details - the chosen line's fields and text. @part fields - its fields. @part raw - its text. @part status - the counts under the lines. @part empty - what is shown when there are no lines. @part error - the message when a log could not be read.
--bmx-log-stream-ansi-2 Terminal green.
--bmx-log-stream-ansi-3 Terminal yellow.
--bmx-log-stream-ansi-4 Terminal blue.
--bmx-log-stream-ansi-5 Terminal magenta.
--bmx-log-stream-ansi-6 Terminal cyan.
--bmx-log-stream-ansi-7 Terminal white.
--bmx-log-stream-ansi-8 Terminal bright black.
--bmx-log-stream-ansi-9 Terminal bright red.
--bmx-log-stream-background Behind the lines.
--bmx-log-stream-debug The debug level's colour.
--bmx-log-stream-error The error level's colour.
--bmx-log-stream-fatal The fatal level's colour.
--bmx-log-stream-font The lines' font. A monospace font.
--bmx-log-stream-font-size The lines' size.
--bmx-log-stream-height How tall the viewer is.
--bmx-log-stream-info The info level's colour.
--bmx-log-stream-match A search match.
--bmx-log-stream-text The lines' text.
--bmx-log-stream-trace The trace level's colour. Also -debug, -info, -warn, -error, -fatal.
--bmx-log-stream-warn The warning level's colour.

<bmx-menu>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxOpenChange boolean Fired when the menu opens or closes.
bmxSelect BmxMenuSelectDetail Fired when an item is chosen.

Methods

MethodSignatureDescription
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

SlotDescription
(default) The default slot

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

SlotDescription
(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

PropertyAttributeTypeDefaultDescription
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

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

<bmx-org-chart>

Properties

PropertyAttributeTypeDefaultDescription
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, exactly as written. 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.
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

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

Methods

MethodSignatureDescription
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

SlotDescription
empty what to draw when there are no nodes at all.

CSS shadow parts

PartDescription
canvas
empty
node-count
node-detail
node-handle
node-label
tree
wire
wires

CSS custom properties

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxChange BmxPaginationChangeDetail Fired when the reader asks for a different page, or a different page size.

Methods

MethodSignatureDescription
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

PartDescription
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

PropertyDescription
--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-pert-chart>

Properties

PropertyAttributeTypeDefaultDescription
columnGap column-gap number 64 Space between columns, in pixels.
holidays holidays string[] | string [] Dates that are not worked, YYYY-MM-DD.
label label string — What the chart is called. Without one it is announced as "Task network".
links links BmxTaskLink[] | string [] The links between tasks.
locale locale string — The locale dates are written in. Defaults to the page's.
nodeHeight node-height number 92 How tall a box is, in pixels.
nodeWidth node-width number 188 How wide a box is, in pixels. A layout input; its looks are CSS.
projectStart project-start string — The first day work can happen, YYYY-MM-DD.
rowGap row-gap number 28 Space between rows, in pixels.
scale scale number 1 How large the chart is drawn, from 0.25 to 2.
showCriticalPath show-critical-path boolean true Draws the critical path in the critical colour.
tasks tasks BmxTask[] | string [] The tasks, as a flat list with parent references - the same list bmx-gantt takes.
workingDays working-days number[] | string [1, 2, 3, 4, 5] Days of the week that are worked, 0 for Sunday.

Events

EventDetailDescription
bmxSelect BmxPertSelectDetail A task was chosen.

Methods

MethodSignatureDescription
exportSvg exportSvg() => Promise<string> The network as a standalone SVG document.
focusTask focusTask(id: string) => Promise<void> Scrolls a task's box into view and focuses it.
getSchedule getSchedule() => Promise<BmxSchedule> The plan as scheduled.
zoomIn zoomIn() => Promise<void> Draws the chart larger.
zoomOut zoomOut() => Promise<void> Draws the chart smaller.
zoomToFit zoomToFit() => Promise<void> Scales the chart to fit its box.

Slots

SlotDescription
empty what to draw when there are no tasks.

CSS shadow parts

PartDescription
canvas
empty
network
node-early
node-late
node-name
node-title
node-wbs
viewport
wires

CSS custom properties

PropertyDescription
--bmx-pert-band-color The date rows at the top and bottom of a box.
--bmx-pert-critical-color A critical box's border and a critical arrow.
--bmx-pert-height How tall the chart's scrolling area is.
--bmx-pert-node-background A box's fill.
--bmx-pert-node-border Its border.
--bmx-pert-node-color Its text.
--bmx-pert-node-height How tall a box is. From node-height.
--bmx-pert-node-radius Its corners.
--bmx-pert-node-width How wide a box is. Written by the component from node-width.
--bmx-pert-wire-color The arrows.
--bmx-pert-wire-width How thick they are. @part viewport - the scrolling area. @part canvas - the drawing, scaled by scale. @part wires - the SVG layer of arrows. @part wire - one arrow. Also wire-critical. @part network - the role="list" that holds the boxes. @part node - one box. Also node-critical, node-milestone, node-selected and node-<category>. @part node-early - the top row: earliest start, length, earliest finish. @part node-title - the outline number and name. @part node-wbs - the outline number. @part node-name - the name. @part node-late - the bottom row: latest start, float, latest finish. @part empty - what is drawn when there are no tasks.

<bmx-pivot-chart>

Properties

PropertyAttributeTypeDefaultDescription
data data BmxPivotChartData | string — The numbers to chart, without a pivot: { categories, series: [{ name, values }] }, or JSON.
for for string | HTMLElement — The pivot grid it charts: its id, a CSS selector, or the element.
label label string — A title over the chart, and its accessible name.
legend legend 'bottom' | 'end' | 'none' 'bottom' Where the legend goes: bottom, end or none.
locale locale string — A BCP 47 locale for numbers. Default: the page's lang.
maxCategories max-categories number 40 At most this many categories.
maxSeries max-series number 10 At most this many series.
stacked stacked boolean false Stack the series (columns, bars and areas).
type type BmxPivotChartType 'column' column (default), bar, line, area, pie or doughnut.
withTotals with-totals boolean false Chart subtotals and grand totals too.

Events

EventDetailDescription
bmxChartSelect BmxPivotChartSelectDetail A bar, point or slice was clicked, or Enter was pressed on it.

Methods

MethodSignatureDescription
refreshChart refreshChart() => Promise<void> Draws again from the pivot.

CSS shadow parts

PartDescription
caption its title.
chart the whole chart.
legend the series.
legend-item one series, a button that shows or hides it.
plot the drawing.
tooltip the value under the pointer.

CSS custom properties

PropertyDescription
--bmx-pivot-chart-area-opacity How solid an area is. Default 0.22.
--bmx-pivot-chart-background Behind the chart.
--bmx-pivot-chart-color-0 The first series (or slice). Colours 0 to 9 are used in turn.
--bmx-pivot-chart-color-1 The second series.
--bmx-pivot-chart-color-2 The third series.
--bmx-pivot-chart-color-3 The fourth series.
--bmx-pivot-chart-color-4 The fifth series.
--bmx-pivot-chart-color-5 The sixth series.
--bmx-pivot-chart-color-6 The seventh series.
--bmx-pivot-chart-color-7 The eighth series.
--bmx-pivot-chart-color-8 The ninth series.
--bmx-pivot-chart-color-9 The tenth series.
--bmx-pivot-chart-grid The value axis lines.
--bmx-pivot-chart-height How tall the drawing is. Default 20rem.

<bmx-pivot-grid>

Properties

PropertyAttributeTypeDefaultDescription
appearance appearance 'modern' | 'striped' | 'bordered' | 'minimal' | 'glass' 'modern' The look: modern, striped, bordered, minimal or glass.
columnSubtotals column-subtotals boolean true A total column after each open column member's columns.
data data BmxPivotRecord[] | string [] The records: an array of objects, or JSON in the attribute.
dataProvider property only (request: BmxPivotServerRequest) => Promise<BmxPivotServerResponse> | BmxPivotServerResponse — Totals from your own server instead of from data: called with the layout (levels, values, filters), it answers every cell, subtotals and grand totals included. Declare the fields with fields. Set from script.
deferUpdates defer-updates boolean false Changes in the field list wait for its Update button.
density density 'compact' | 'standard' | 'comfortable' 'standard' Line height: compact, standard or comfortable.
drillPanel drill-panel boolean true Show the records behind a cell in a panel when it is drilled through, unless bmxPivotDrillThrough is cancelled.
drillProvider property only (request: BmxPivotServerDrillRequest) => Promise<BmxPivotRecord[]> | BmxPivotRecord[] — The records behind a cell from your server, for drill-through when totals come from dataProvider. Set from script.
emptyCell empty-cell string '' What an empty cell shows.
expandDepth expand-depth number — How many levels start open. Default: all of them.
fieldList field-list 'auto' | 'open' | 'closed' | 'none' 'auto' The field list: auto (open when the grid is wide enough), open, closed, or none for no field list at all.
fields fields BmxPivotFieldDef[] | string [] The fields: { field, title?, type?, format?, dateParts?, bin?, order?, folder?, hidden? }, or JSON. Fields not listed are read from the records.
fileName file-name string 'pivot' The name exported files are saved under.
formatRules format-rules BmxPivotFormatRule[] | string [] Conditional formatting, as data: [{ type: 'bars' | 'scale' | 'icons' | 'highlight', value?, scope?, when?, tone?, textTone?, bold?, tones?, icons?, reverse? }], or JSON. The reader can add them from a value's menu.
grandTotals grand-totals 'both' | 'rows' | 'columns' | 'none' 'both' Grand totals: a last row and a last column (both), the row only (rows), the column only (columns), or none.
hierarchies hierarchies BmxPivotHierarchy[] | string [] Groups of levels offered as one item in the field list: { name, title?, levels }, or JSON.
label label string — The accessible name. Default: "Pivot".
layout layout BmxPivotLayout | string {} What goes where: { rows, columns, filters, values, valuesOn, settings }, or JSON.
loading loading boolean false Show a loading bar: set while your own data is on its way.
locale locale string — A BCP 47 locale for numbers, dates, member names and sorting. Default: the page's lang, then the reader's.
lockLayout lock-layout boolean false The reader may sort, filter, open and close, but not move fields or change values.
memberProvider property only (level: string) => Promise<readonly { key: string; label?: string }[]> | readonly { key: string; label?: string }[] — A level's members from your server, for filters and slicers when totals come from dataProvider. Set from script.
requestInit property only RequestInit — Options for fetching src: headers, credentials.
rowLayout row-layout 'compact' | 'tabular' 'compact' Row headings in one indented column (compact) or one column per level (tabular).
src src string — A URL to load the records from: JSON, JSON lines, CSV or TSV.
stateKey state-key string — A name to keep the reader's workspace under in this browser: layout, open members, widths.
strings strings Partial<BmxPivotGridStrings> | string — Every word the grid shows, for another language: any of them, or JSON.
subtotals subtotals 'top' | 'bottom' | 'none' 'top' Where an open row member's total goes: on its own line (top), after its members (bottom), or nowhere.
timeZone time-zone 'local' | 'utc' 'local' How a moment with a time of day becomes a day: in the reader's zone (local) or utc. A bare date is always its own day.
toolbar toolbar boolean true Show the toolbar.
worker worker 'auto' | 'always' | 'never' 'auto' Total on a background thread: auto (from worker-threshold records), always, or never.
workerThreshold worker-threshold number 50000 Records from which auto uses a background thread.

Events

EventDetailDescription
bmxPivotCellClick BmxPivotCellDetail A cell was clicked.
bmxPivotDrillThrough BmxPivotDrillThroughDetail A cell was double-clicked or Enter pressed on it: the records behind it. Cancelable.
bmxPivotError BmxPivotErrorDetail The records could not be loaded or totalled.
bmxPivotLayoutChange BmxPivotLayoutChangeDetail The layout changed.
bmxPivotStateChange BmxPivotStateChangeDetail Something the reader can save changed: the layout, what is open, a width.
bmxPivotToggle BmxPivotToggleDetail A member was opened or closed.
bmxPivotUpdate BmxPivotUpdateDetail New totals are on show - with the numbers arranged for a chart.

Methods

MethodSignatureDescription
appendData appendData(records: BmxPivotRecord[]) => Promise<void> Adds records after those held, and totals again shortly after: call it with each chunk as a large set arrives. Columns already read are extended rather than read again.
collapseAll collapseAll(axis?: BmxPivotAxisName) => Promise<void> Closes every member, on one axis or both.
download download(format?: "xlsx" | "csv", options?: { records?: boolean; fileName?: string; }) => Promise<void> Saves what is on show as a file: xlsx or csv.
drillThrough drillThrough(rowPath: string[], columnPath: string[], limit?: number) => Promise<BmxPivotRecord[]> The records behind a total, by the member paths of its row and column. At most limit.
expandAll expandAll(axis?: BmxPivotAxisName) => Promise<void> Opens every member, on one axis or both.
expandToLevel expandToLevel(axis: BmxPivotAxisName | "both", depth: number) => Promise<void> Opens the levels above depth and closes the rest: 1 shows the outermost level's members, open.
exportData exportData(format?: "xlsx" | "csv" | "html", options?: { records?: boolean; }) => Promise<Blob> What is on show as a file: xlsx (the pivot as a styled sheet, headings merged, rows as an outline, conditional formats kept; with records: true the records behind it as a second sheet), csv, or html for printing.
getCellValue getCellValue(rowPath: string[], columnPath: string[], valueId?: string) => Promise<number | null> A total by the member paths of its row and column; the first value when none is named.
getChartData getChartData(options?: { maxCategories?: number; maxSeries?: number; withTotals?: boolean; }) => Promise<BmxPivotChartData> The totals on show arranged for a chart: a category per row, a series per column and value.
getLayout getLayout() => Promise<BmxPivotLayout> The layout, as JSON can carry it.
getLevelTitle getLevelTitle(level: string) => Promise<string> A level's name: "Region", or "Order date (Year)"; the key itself when there is no such level.
getMembers getMembers(level: string) => Promise<{ key: string; label: string; count: number | null; selected: boolean; }[]> A level's members in order, each with how many records it has under every other filter (null when totals come from a server) and whether the level's own filter keeps it. What bmx-pivot-slicer shows.
getPrintHtml getPrintHtml() => Promise<string> What is on show as a page to print: headings repeated on every page.
getState getState() => Promise<BmxPivotState> Everything the reader can change - layout, open members, widths, view - as JSON.
getText getText() => Promise<string> What is on show as text: tab-separated, headings first.
load load(source: string | URL | Blob) => Promise<void> Loads records from a URL, a File or Blob, or text: JSON, JSON lines, CSV or TSV.
print print() => Promise<void> Prints what is on show.
redo redo() => Promise<boolean> Steps the layout forward again.
refresh refresh() => Promise<void> Totals again from the records: after changing records in place.
setData setData(records: BmxPivotRecord[]) => Promise<void> Replaces the records.
setLayout setLayout(layout: BmxPivotLayout | string) => Promise<void> Replaces the layout. The reader can undo it.
setMemberFilter setMemberFilter(level: string, keys: string[] | null) => Promise<void> Keeps only these members of a level (their keys), whether or not the level is placed; null keeps them all.
setState setState(state: BmxPivotState | string) => Promise<boolean> Restores what getState gave. Returns false when it was not state at all.
settled settled() => Promise<void> Resolves once the totals for everything set so far are on show.
showFieldList showFieldList(open?: boolean) => Promise<void> Opens or closes the field list.
toggleMember toggleMember(axis: BmxPivotAxisName, path: string[], open?: boolean) => Promise<boolean> Opens or closes a member by its path of keys. Returns whether anything changed.
undo undo() => Promise<boolean> Steps the layout back.

Slots

SlotDescription
toolbar-end your own controls at the end of the toolbar.
toolbar-start your own controls at the start of the toolbar.

CSS shadow parts

PartDescription
add-calculated the button that adds a calculated value.
chip a field placed in an area.
drag-ghost the label that follows the pointer while a field is dragged.
drill-panel the panel of records behind a cell.
empty what is shown before any field is placed, or when no record matches.
error what is shown when the records could not be loaded or totalled.
field a field in the list.
field-list the field list.
field-search its search field.
grid the scrolling grid.
loading the bar shown while totals are worked out.
matrix the area holding the grid.
member-search the search in a member filter.
menu a pop-up: a field's menu, a value's menu, a filter, a formula.
menu-item one of its commands.
status the record count and timing in the toolbar.
tool-button a tool. The field list's tool is also fields-button.
toolbar the bar of tools above the grid.
update-button the field list's Update button, when updates are deferred.
zone one of the four areas: Filters, Columns, Rows, Values.

CSS custom properties

PropertyDescription
--bmx-pivot-grid-active The ring around the active cell.
--bmx-pivot-grid-background Behind the cells.
--bmx-pivot-grid-bar-opacity How strong a data bar is, 0-100%. Default 34%.
--bmx-pivot-grid-cell-padding Space either side of a cell's content.
--bmx-pivot-grid-chip-background A field placed in an area.
--bmx-pivot-grid-font-size The cells' text size.
--bmx-pivot-grid-grand-background A grand total.
--bmx-pivot-grid-header-background Behind the headings.
--bmx-pivot-grid-header-height Each heading row's height.
--bmx-pivot-grid-header-text The headings' text.
--bmx-pivot-grid-height How tall the grid is, toolbar included.
--bmx-pivot-grid-indent How far each row level is indented, in the compact form.
--bmx-pivot-grid-line The lines between cells.
--bmx-pivot-grid-negative The text of a negative total.
--bmx-pivot-grid-panel-background Behind the field list.
--bmx-pivot-grid-panel-width The field list's width.
--bmx-pivot-grid-radius The corners of the grid.
--bmx-pivot-grid-range The chosen cells.
--bmx-pivot-grid-row-alternate Every other line, in the striped look.
--bmx-pivot-grid-row-height Each line's height. Set it to override the density.
--bmx-pivot-grid-row-hover A line under the pointer.
--bmx-pivot-grid-scrollbar-thumb The scrollbars' thumbs.
--bmx-pivot-grid-scrollbar-track The scrollbars' tracks.
--bmx-pivot-grid-subtotal-background A subtotal.

<bmx-pivot-slicer>

Properties

PropertyAttributeTypeDefaultDescription
columns columns number 2 Columns, for the grid layout.
field field string '' The level it filters: a field (region) or a part of a date field (orderDate:year).
for for string | HTMLElement — The pivot grid it filters: its id, a CSS selector, or the element.
hideEmpty hide-empty boolean false Hide members with no records under the pivot's other filters, rather than dimming them.
label label string — Its heading. Default: the field's name from the pivot.
layout layout 'buttons' | 'grid' | 'list' 'buttons' buttons (default, wrapping), grid (in columns columns) or list (one per line).
multiple multiple boolean true Choose several members (default), or one at a time.
search search 'auto' | 'always' | 'never' 'auto' A search box: from 12 members (auto), always or never.
showCounts show-counts boolean true Show how many records each member has.

Events

EventDetailDescription
bmxSlicerChange BmxPivotSlicerChangeDetail The choice changed.

Methods

MethodSignatureDescription
clear clear() => Promise<void> Shows every member again.
getSelected getSelected() => Promise<string[] | null> The member keys kept, or null when all are.
refreshMembers refreshMembers() => Promise<void> Reads the members again from the pivot.
select select(keys: string[] | null) => Promise<void> Keeps only these members (their keys); an empty list or null keeps them all.

CSS shadow parts

PartDescription
clear the button that shows every member again.
count how many records a member has.
head its heading row.
option one member. Also option-selected when it is chosen.
options the members.
search the search field.
slicer the whole slicer.
title its heading.

CSS custom properties

PropertyDescription
--bmx-pivot-slicer-background Behind the slicer.
--bmx-pivot-slicer-max-height How tall the list may grow before it scrolls. Default 16rem.
--bmx-pivot-slicer-option-background A member.
--bmx-pivot-slicer-radius The slicer's corners.
--bmx-pivot-slicer-selected-background A chosen member.
--bmx-pivot-slicer-selected-text A chosen member's text.
--bmx-pivot-slicer-width How wide the slicer is. Default 14rem.

<bmx-popover>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxToggle BmxPopoverToggleDetail Fired when it opens or closes, saying which and why.

Methods

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

Slots

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

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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 - it returns the declared text, var() and all - 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

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

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

Slots

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

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxChange BmxRadioGroupChangeDetail Fired when the chosen option changes.
bmxValidityChange BmxRadioGroupValidityDetail Fired whenever the resolved validity changes.

Methods

MethodSignatureDescription
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

SlotDescription
(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

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

CSS custom properties

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
description Rich help text, in place of the description property.
label Rich label content, in place of the label property.

CSS shadow parts

PartDescription
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

PropertyDescription
--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-report-designer>

Properties

PropertyAttributeTypeDefaultDescription
data data readonly Record<string, unknown>[] | string [] Sample rows: an array of objects, or JSON text. They give the field list and the preview its data.
dataUrl data-url string — A URL to fetch the sample rows from, as a JSON array. Takes the place of data.
fields fields readonly BmxReportFieldSpec[] | string [] The fields to offer, when there is no data to find them in: names, or { name, type } with type number, text, date or boolean. JSON text works too.
fileName file-name string — The name the JSON is saved under. Defaults to the report's title.
gallery gallery boolean true Offers the template gallery, and opens it when there is no report.
gridSize grid-size number 4 The grid spacing in points. Items snap to it.
label label string — The designer's accessible name.
locale locale string — The locale for sample values and the preview. Defaults to the report's language.
mode mode 'design' | 'preview' | 'json' 'design' design, preview (the report run in a viewer) or json (the definition as text).
report report BmxReport | string | null null The report being designed: an object, or JSON text. The designer writes each edit back to it.
requestInit property only RequestInit — Options for the fetch - headers, credentials. Script only.
showGrid show-grid boolean true Draws the grid on the bands.
snap snap boolean true Items snap to the grid and to each other while they are dragged. Hold Alt to place freely.
zoom zoom number | string 'page-width' The design surface's scale: page-width fits the page to the surface; 1 is actual size, 1.5 is 150%.

Events

EventDetailDescription
bmxReportChange BmxReportChangeDetail Every change to the report: an edit, undo or redo, a template, or JSON applied.
bmxReportSave BmxReportSaveDetail Save was pressed. Cancel it to store the report yourself; otherwise the JSON downloads.
bmxSelectionChange BmxReportSelectionDetail The selection changed.

Methods

MethodSignatureDescription
downloadJson downloadJson(fileName?: string) => Promise<void> Saves the report as a JSON file.
getJson getJson() => Promise<string> The report as JSON text.
getReport getReport() => Promise<BmxReport> The report as it is now.
newReport newReport(template?: string, title?: string) => Promise<BmxReport> Replaces the report with one built from a template in the gallery: blank, list, grouped, summary, letter.
redo redo() => Promise<boolean> Redoes the last edit undone.
select select(ids: readonly string[]) => Promise<void> Selects items by id.
undo undo() => Promise<boolean> Undoes the last edit. Resolves to whether there was one.

Slots

SlotDescription
toolbar-end extra controls at the end of the toolbar.

CSS shadow parts

PartDescription
builder
button
card
completions
data-field
empty
field
field-error
gallery
insert-panel
json
main
mode
preview
problems
properties-panel
properties-title
status-bar
surface
template
tool
toolbar
zoom

CSS custom properties

PropertyDescription
--bmx-report-designer-desk The area around the page.
--bmx-report-designer-guide The lines drawn while an item snaps. @part toolbar - the row of controls. @part mode - the Design, Preview and JSON buttons. @part button - a button. @part zoom - the zoom list. @part main - the panels and the design surface. @part insert-panel - the toolbox, field list and outline. @part tool - a toolbox entry. @part data-field - a field in the field list. @part surface - the scrolling design surface. @part empty - what the surface shows when the report has no bands. @part properties-panel - the properties of the selection. @part properties-title - its heading. @part field - a labelled property. @part field-error - an expression's error under its field. @part completions - the suggestion list under an expression field. @part card - a group, sort key, field, parameter or condition in the properties. @part status-bar - the problems count, selection and zoom at the foot. @part problems - the list of problems. @part preview - the report viewer in Preview. @part json - the JSON view. @part builder - the expression builder dialog. @part gallery - the template gallery dialog. @part template - a template in it.
--bmx-report-designer-height How tall the designer is.
--bmx-report-designer-insert-width How wide the insert panel is.
--bmx-report-designer-properties-width How wide the properties panel is.
--bmx-report-designer-selection The outline and handles of the selection.

<bmx-report-viewer>

Properties

PropertyAttributeTypeDefaultDescription
data data readonly Record<string, unknown>[] | string [] The rows: an array of objects, or JSON text.
dataUrl data-url string — A URL to fetch the rows from, as a JSON array. Takes the place of data.
drillData property only (report: string, parameters: Readonly<Record<string, unknown>>, signal: AbortSignal) => readonly unknown[] | undefined | null | Promise<readonly unknown[] | undefined | null> — Rows for a drill-through, when it needs other rows than the viewer's: called with the report's name and the parameters it opens with. Return the rows, or nothing to use the viewer's own. Script only.
exports exports readonly BmxReportFormat[] | string ['pdf', 'xlsx', 'csv', 'html'] The exports the toolbar offers, in order: any of pdf, xlsx, csv, html. A space-separated list in markup.
fileName file-name string — The name the PDF is saved under. Defaults to the report's title.
label label string — The viewer's accessible name. Defaults to the report's title.
locale locale string — The locale for numbers and dates. Defaults to the report's language, then the page's.
parameters parameters Record<string, unknown> | string {} Parameter values: an object, or JSON text. The reader can change them in the parameters panel.
report report BmxReport | string | null null The report definition: an object, or JSON text.
reportUrl report-url string — A URL to fetch the report definition from. Used when report is not set.
reports property only Readonly<Record<string, BmxReport | string | BmxReportSource>> — Reports a drill-through can open, by name: definitions, or URLs to fetch them from, or { report, data } for a report with rows of its own. A name that is not here is fetched as a URL. Script only.
requestInit property only RequestInit — Options for both fetches - headers, credentials. Script only.
sidebar sidebar 'pages' | 'contents' | 'none' 'none' The side panel: pages (thumbnails), contents, or none.
toolbar toolbar boolean true Shows the toolbar.
zoom zoom string | number 'page-width' page-width, whole-page, or a scale: 1 is actual size, 1.5 is 150%.

Events

EventDetailDescription
bmxPageChange BmxReportPageDetail The page in view changed.
bmxParametersChange BmxReportParametersDetail The reader applied new parameter values.
bmxReportDrill BmxReportDrillDetail The reader opened a drill-through. Cancel it to open the report yourself.
bmxReportRender BmxReportRenderDetail The report has been laid out, or could not run for want of parameters.
bmxReportSort BmxReportSortDetail The reader sorted the report by clicking a column heading.

Methods

MethodSignatureDescription
back back() => Promise<boolean> Goes back from a drill-through to the report it was opened from. Resolves to whether there was one.
download download(format?: BmxReportFormat, fileName?: string) => Promise<void> Saves the report as a file, under fileName or the report's title.
downloadPdf downloadPdf(fileName?: string) => Promise<void> Saves the report as a PDF, under fileName or the report's title.
exportAs exportAs(format?: BmxReportFormat) => Promise<Blob> The report as a file: pdf, xlsx (its data), csv (its data) or html (its pages).
exportPdf exportPdf() => Promise<Blob> The report as a PDF file.
find find(text: string) => Promise<number> Finds text in the report and shows the first match. Resolves to the number of matches.
getDocument getDocument() => Promise<BmxReportDocument | null> The laid-out report: its pages, bookmarks and problems.
goToPage goToPage(page: number) => Promise<void> Scrolls to a page, 1-based.
print print() => Promise<void> Prints the report: every page, at its own paper size.
refresh refresh() => Promise<void> Lays the report out again - after the data behind a URL has changed, say.
zoomIn zoomIn() => Promise<void> Zooms in a step.
zoomOut zoomOut() => Promise<void> Zooms out a step.

Slots

SlotDescription
empty what to show when there is no report.
toolbar-end extra controls at the end of the toolbar.

CSS shadow parts

PartDescription
back-button
body
bookmark
button
contents
drill
empty
error
export-list
export-option
find
find-count
find-input
page
page-input
parameter
parameters
parameters-hint
run-button
sidebar
sidebar-tab
sort
status
thumbnail
thumbnails
toggle
toolbar
viewport
zoom

CSS custom properties

PropertyDescription
--bmx-report-viewer-canvas The area behind the pages.
--bmx-report-viewer-control The colour of a group's toggle and a heading's sort arrow on the page.
--bmx-report-viewer-control-hover The wash over a sortable heading or a drill-through under the pointer. @part toolbar - the row of controls. @part button - a toolbar button. The Back button is also back-button. @part export-list - the list of file types under the Export button. @part export-option - one of them. @part page-input - the page number field. @part zoom - the zoom list. @part find - the search group. @part find-input - the search field. @part find-count - "3/12" beside it. @part parameters - the parameters panel. @part parameters-hint - the note that required values are missing. @part parameter - one parameter's field. @part run-button - the button that runs the report. @part body - the side panel and the pages. @part sidebar - the side panel. @part sidebar-tab - its Pages and Contents buttons. @part thumbnails - the list of page thumbnails. @part thumbnail - one of them. @part contents - the contents list. @part bookmark - one entry in it. @part viewport - the scrolling area that holds the pages. @part page - one page. Pages are always white: they are paper. @part match - a search match. Also match-current. @part toggle - the button beside a group's heading that shows or hides its details. @part sort - a heading that sorts the report when clicked. @part drill - a value that opens another report when clicked. @part status - the "Preparing report" notice. @part empty - what is shown when there is no report. @part error - the message when the report could not be loaded.
--bmx-report-viewer-height How tall the viewer is.
--bmx-report-viewer-match A search match on the page.
--bmx-report-viewer-match-current The match being shown.
--bmx-report-viewer-page-shadow The shadow under each page.
--bmx-report-viewer-sidebar-width How wide the side panel is.

<bmx-rich-text-editor>

Properties

PropertyAttributeTypeDefaultDescription
author author string 'You' The name tracked changes and comments are written under.
comments comments readonly BmxRteComment[] | string [] The comments on the document. JSON in markup. Updated as comments are added, answered and resolved.
disabled disabled boolean false Neither editable nor posted with its form.
fullscreen fullscreen boolean false Show the editor over the whole window.
hideChanges hide-changes boolean false Show tracked deletions struck through (default) or hide them, showing the text as it would read.
imageHandler property only (file: File) => Promise<string> — Stores an image the reader adds and returns its URL. Default: the image is kept in the document as data.
images images boolean true Allow images.
label label string — What the editor is for, said by screen readers.
markdownShortcuts markdown-shortcuts boolean true Turn # , - , 1. , > , [] , ``` and **bold** into formatting as they are typed.
maxLength max-length number — At most this many characters of text.
mentionSource property only (query: string) => readonly BmxRteMentionItem[] | Promise<readonly BmxRteMentionItem[]> — Finds people to
mentions mentions readonly BmxRteMentionItem[] | string — People (or anything) to
name name string — The name the value is posted under with its form.
placeholder placeholder string — Shown while the document is empty.
readonly readonly boolean false Shown but not editable.
required required boolean false The form will not submit while the document is empty.
spellcheck spellcheck boolean true Underline misspellings, as the browser does.
statusBar status-bar boolean true Show the word count and the review buttons under the document.
strings strings Partial<BmxRteStrings> | string — Words the editor shows or says: any of BmxRteStrings. JSON in markup.
toolbar toolbar string | readonly string[] 'full' The toolbar: full (default), basic, minimal, or a list of items (bold,italic,|,link).
toolbarMode toolbar-mode 'top' | 'bubble' | 'both' | 'none' 'top' Where the toolbar is: top (default), bubble (over a selection), both or none.
tracking tracking boolean false Record typing and deleting as changes to accept or reject.
value value string '' The document as HTML. Set it to load one; read it (or listen for bmxRteInput) for what was written.

Events

EventDetailDescription
bmxRteChange BmxRteValueDetail The document changed and the editor lost focus, as a field's change does.
bmxRteCommentsChange BmxRteCommentsDetail A comment was added, answered, resolved, reopened or deleted. comments is the whole new list.
bmxRteInput BmxRteValueDetail The document changed (typing, a command, a paste).
bmxRteMention BmxRteMentionDetail Someone was
bmxRteSelectionChange BmxRteFormats The formats at the caret changed.
bmxRteTrackedChange BmxRteChangesDetail The tracked changes changed.

Methods

MethodSignatureDescription
acceptChange acceptChange(id?: string) => Promise<number> Accepts one tracked change by id, or all of them.
addCommentToSelection addCommentToSelection(text: string) => Promise<string | null> Adds a comment to the selected text. Returns its id, or null with nothing selected.
clear clear() => Promise<void> Empties the document.
execCommand execCommand(name: string, value?: string) => Promise<void> Runs a command, as its toolbar button does: bold, italic, underline, strike, code, p, h1-h6, quote, codeBlock, bulletList, orderedList, checklist, alignLeft, alignCenter, alignRight, alignJustify, indent, outdent, textColor and highlight (with a colour), unlink, rule, clear, undo, redo, find, track, source, fullscreen and the table commands.
getChanges getChanges() => Promise<readonly BmxRteChange[]> Every tracked change.
getStats getStats() => Promise<{ words: number; characters: number; }> Words and characters.
insertHTML insertHTML(html: string) => Promise<void> Inserts HTML (sanitised) at the caret, or at the end when the editor has none.
insertTableAt insertTableAt(cols?: number, rows?: number) => Promise<void> Inserts a table of cols by rows (the first row a header).
insertText insertText(text: string) => Promise<void> Inserts text at the caret.
loadHTML loadHTML(html: string, keepHistory?: boolean) => Promise<void> Loads HTML (sanitised). With keepHistory, the change can be undone.
loadMarkdown loadMarkdown(markdown: string, keepHistory?: boolean) => Promise<void> Loads Markdown.
redo redo() => Promise<void> Redoes what was undone.
rejectChange rejectChange(id?: string) => Promise<number> Rejects one tracked change by id, or all of them.
replaceAll replaceAll(query: string, replacement: string, matchCase?: boolean) => Promise<number> Replaces every match of query with replacement. Returns how many.
setFocus setFocus() => Promise<void> Moves focus into the document.
setLink setLink(href: string, newTab?: boolean) => Promise<void> Adds a link to the selection, or changes the one at the caret.
toDocumentJSON toDocumentJSON() => Promise<BmxRteJsonNode> The document as a tree of blocks, marks and text.
toHTML toHTML() => Promise<string> The document as sanitised HTML (the same as value).
toMarkdown toMarkdown() => Promise<string> The document as Markdown (GitHub's dialect).
toText toText() => Promise<string> The text, as a reader sees it, with tracked deletions left out.
undo undo() => Promise<void> Undoes the last change.

Slots

SlotDescription
surface (managed by the editor) the editing surface.

CSS shadow parts

PartDescription
bubble the toolbar over a selection.
button a toolbar button.
comments the comments panel.
find the find and replace bar.
frame the editor's border and background.
popover a menu or form opened from the toolbar.
source the HTML source view.
status the status bar.
toolbar the toolbar.

CSS custom properties

PropertyDescription
--bmx-rich-text-editor-background Behind the document.
--bmx-rich-text-editor-font The document's typeface. Default the library's.
--bmx-rich-text-editor-font-size The document's text size. Default 1rem.
--bmx-rich-text-editor-max-height The document's greatest height before it scrolls. Default none.
--bmx-rich-text-editor-min-height The document's least height. Default 10rem.
--bmx-rich-text-editor-toolbar-background Behind the toolbar.

<bmx-scheduler>

Properties

PropertyAttributeTypeDefaultDescription
conflicts conflicts 'allow' | 'warn' | 'prevent' 'warn' Clashes: allow (not shown), warn (shown and announced) or prevent (refused).
currentTime current-time string — The moment taken as now (ISO), for repeatable pages and tests. Default: the clock.
date date string — A date in the range on show (2026-10-05). Default: today.
dayEnd day-end string '24:00' See day-start.
dayStart day-start string '00:00' The part of each day drawn in the day and week views: 07:00 to 20:00, say.
dayWidth day-width number 56 Pixels per day in the month view.
defaultDuration default-duration number 60 Minutes a booking lasts when made by a double-click, or given without an end.
editor editor boolean true Whether double-click and Enter open the built-in editor.
events events BmxSchedulerEvent[] | string [] Bookings: [{ id, title, start, end?, resourceId | resourceIds, recurrence?, ... }], as a property or JSON. Changes write back here.
firstDayOfWeek first-day-of-week number — 0 for Sunday to 6 for Saturday. Default: the locale's.
groupBy group-by string 'group' The resource field resources are grouped by; empty for no groups.
holidays holidays string[] | string [] Dates no one works (2026-12-25): a list, or text separated by commas.
hourWidth hour-width number — Pixels per hour in the day and week views. Default: 72 for a day, 16 for a week.
label label string — An accessible name for the scheduler.
locale locale string — A BCP 47 locale for dates and times. Default: the page's.
outsideHours outside-hours 'allow' | 'warn' | 'prevent' 'allow' Bookings outside working hours: allow, warn or prevent.
readonly readonly boolean false No making, moving, resizing or deleting.
recurrenceEdits recurrence-edits 'ask' | 'occurrence' | 'series' 'ask' Changing one occurrence of a series: ask, or always the occurrence or the series.
requestInit request-init RequestInit | string — Options for the src request (headers, credentials), as a property or JSON.
resourceWidth resource-width number 220 The width of the resource column, in pixels.
resources resources BmxSchedulerResource[] | string [] Things that can be booked: [{ id, name, group?, maxConcurrent?, workingHours?, timeZone?, unavailable? }], as a property or JSON.
responsive responsive boolean true A narrow scheduler (under 640 pixels) shows the agenda.
rowHeight row-height number 44 The least a row is high, in pixels. Rows grow to hold overlapping bookings.
showUtilisation show-utilisation boolean true Whether each resource shows its utilisation.
slotMinutes slot-minutes number 15 The step bookings snap to, in minutes.
src src string — A URL to load { resources, events } from as JSON, or bookings from an .ics file.
strings strings Partial<BmxSchedulerStrings> | string — Words to show instead of the English ones, as a property or JSON.
timeZone time-zone string — The zone everything is drawn in (IANA name: Europe/London). Default: the reader's.
view view BmxSchedulerView 'week' day, week, month or agenda.
workWeek work-week boolean false The week view shows only working days (those in working-hours).
workingHours working-hours string | BmxSchedulerWorkingSpan[] 'Mon-Fri 09:00-17:00' When resources work, unless they say otherwise: text like Mon-Fri 09:00-17:00, or spans.

Events

EventDetailDescription
bmxSchedulerChange BmxSchedulerChangeDetail Bookings changed: the whole new list.
bmxSchedulerEventActivate BmxSchedulerActivateDetail A booking was opened. Cancel it to show your own editor.
bmxSchedulerEventChange BmxSchedulerEventChangeDetail A booking is about to change. Cancel it to refuse the change.
bmxSchedulerEventCreate BmxSchedulerCreateDetail A reader asked for a new booking. Cancel it to make your own.
bmxSchedulerRangeChange BmxSchedulerRangeChangeDetail The range on show changed.
bmxSchedulerSelect BmxSchedulerSelectDetail The chosen booking changed.

Methods

MethodSignatureDescription
addEvent addEvent(event: BmxSchedulerEvent) => Promise<boolean> Adds a booking. False when it is refused (by a cancelled bmxSchedulerEventChange or a clash under conflicts="prevent").
downloadICS downloadICS(fileName?: string) => Promise<void> Saves every booking as an .ics file through the browser's download.
findSlot findSlot(request: Omit<BmxSchedulerSlotRequest, "from" | "to"> & { from?: string | number | Date; to?: string | number | Date; }) => Promise<{ start: string; end: string; resourceIds: string[]; } | null> The earliest time resources are free for a booking: all of them, or any one with match: 'any', in working hours unless workingHoursOnly is false. Times come back as ISO instants. Null when there is none in the next 90 days (or before to).
getConflicts getConflicts(from?: string | number | Date, to?: string | number | Date) => Promise<BmxSchedulerConflict[]> The clashes between two times (default: the range on show).
getEvents getEvents() => Promise<BmxSchedulerEvent[]> Every booking, as the page would save it.
getOccurrences getOccurrences(from?: string | number | Date, to?: string | number | Date) => Promise<BmxSchedulerOccurrence[]> The bookings between two times (default: the range on show), series expanded into occurrences.
getUtilisation getUtilisation(from?: string | number | Date, to?: string | number | Date) => Promise<BmxSchedulerUtilisation[]> Each resource's utilisation between two times (default: the range on show).
goToDate goToDate(date: string | Date) => Promise<void> Shows the range around a date.
load load(url: string) => Promise<void> Loads { resources, events } as JSON, or bookings from an .ics file, from a URL.
loadICS loadICS(source: string | Blob, merge?: boolean) => Promise<number> Reads bookings from an .ics file (its text or a File), replacing them, or adding with merge.
next next() => Promise<void> The next range.
openEditor openEditor(id?: string) => Promise<void> Opens the editor on a booking (by id), or on a new one.
previous previous() => Promise<void> The previous range.
redo redo() => Promise<boolean>
removeEvent removeEvent(id: string) => Promise<boolean> Removes a booking (a whole series, for a repeating one).
scrollToTime scrollToTime(time: string | number | Date) => Promise<void> Scrolls the timeline to a time (09:00 on the range's first day, or an instant).
setFocus setFocus() => Promise<void> Moves focus to the chosen booking, or the first one on show.
toICS toICS(name?: string) => Promise<string> Every booking as an iCalendar (.ics) file's text.
today today() => Promise<void> The range with today in it, scrolled to now.
undo undo() => Promise<boolean>
updateEvent updateEvent(id: string, changes: Partial<BmxSchedulerEvent>) => Promise<boolean> Changes a booking's fields. False when there is no such booking or the change is refused.

CSS shadow parts

PartDescription
agenda the agenda list.
blocked time a resource is unavailable.
dialog the editor, the "which occurrences" question and the time finder.
event a booking. Also event-selected, event-clash, event-tentative, event-cancelled, event-recurring.
ghost a booking being dragged, or the time being dragged over to make one.
group a group's row. Also group-collapsed.
handle a booking's resize grip.
header the dates and hours across the top.
lane a row's timeline.
non-working time outside working hours.
now the line at the current time.
range-label the dates on show.
resource a resource's cell at the start of its row.
row a resource's row.
scroller the scrolling timeline.
status the status bar under the timeline.
tick one date or hour in it. Also tick-today.
tick-hour
toolbar the navigation, view and tool buttons.
toolbar-button one of them.
utilisation a resource's utilisation bar.

CSS custom properties

PropertyDescription
--bmx-scheduler-blocked-color The stripes over time a resource is unavailable.
--bmx-scheduler-border The lines between rows, days and hours.
--bmx-scheduler-clash-color The outline and mark of a clash.
--bmx-scheduler-event-background A booking without a colour of its own.
--bmx-scheduler-event-color Text on a booking.
--bmx-scheduler-event-radius A booking's corners.
--bmx-scheduler-header-background The dates and hours across the top, and the resource column's heading.
--bmx-scheduler-height How tall the timeline is (the toolbar and status bar add to it).
--bmx-scheduler-non-working-background Time outside working hours.
--bmx-scheduler-now-color The line at the current time.
--bmx-scheduler-resource-background The resource column.
--bmx-scheduler-today-background Today's column in the header.

<bmx-select>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
(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

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

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

CSS custom properties

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

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

Methods

MethodSignatureDescription
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

SlotDescription
(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

PartDescription
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

PropertyDescription
--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-sparkline>

Properties

PropertyAttributeTypeDefaultDescription
band band readonly number[] | string — A shaded band of normal values: [low, high], or "low,high".
format format BmxChartNumberFormat | string — How values are written: percent, currency:EUR, decimal:1, compact, or the object.
label label string — What the values are, read before the description ("Revenue, last six months").
labels labels readonly string[] | string — Names for the values, read by the pointer ("Jan,Feb,Mar").
locale locale string — A BCP 47 locale for numbers. Default: the page's lang.
markers markers 'none' | 'last' | 'minmax' | 'all' 'last' Dots on none, the last value (default), the minmax and last, or all.
max max number — The top of the scale. Default: the highest value.
min min number — The bottom of the scale. Default: the lowest value.
strings strings Partial<BmxSparklineStrings> | string — Words it is read with, to translate: any of BmxSparklineStrings. JSON in markup.
target target number — A bullet's target.
type type BmxSparklineType 'line' line (default), area, column, winloss or bullet.
values values readonly (number | null)[] | string — The values, oldest first: a list, or comma-separated in markup. An empty entry is a gap.

CSS shadow parts

PartDescription
sparkline the drawing.
tooltip the value under the pointer.

CSS custom properties

PropertyDescription
--bmx-sparkline-band The band of normal values.
--bmx-sparkline-color The line, area and columns.
--bmx-sparkline-height How tall it is. Default 1.4em.
--bmx-sparkline-high The highest value's marker.
--bmx-sparkline-low The lowest value's marker.
--bmx-sparkline-negative Columns below zero, and losses.
--bmx-sparkline-width How wide it is. Default 6em.

<bmx-split-button>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
(default) The primary action's label.
start An icon for the primary action.

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

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

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
description Rich help text, in place of the description property.
label Rich caption content, in place of the label property.

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

SlotDescription
(default) The panel's content.

CSS shadow parts

PartDescription
base The panel itself.

CSS custom properties

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

<bmx-tabs>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxChange BmxTabsChangeDetail Fired when a different panel is chosen.

Methods

MethodSignatureDescription
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

SlotDescription
(default) bmx-tab-panel elements.

CSS shadow parts

PartDescription
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

PropertyDescription
--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-task-board>

Properties

PropertyAttributeTypeDefaultDescription
applyChanges apply-changes boolean true Whether a move is applied by the board itself. Off to own the list entirely.
canMove property only (detail: BmxTaskBoardMoveDetail) => boolean — Whether a move may be made, asked while a card is carried. A function, set from script.
columns columns (string | BmxBoardColumn)[] | string [] The columns, as status values in order: columns="To do,In progress,Done", or objects with a label and a limit from script. Left empty, the statuses the tasks use are the columns.
editable editable boolean false Lets the reader move cards.
holidays holidays string[] | string [] Dates that are not worked, YYYY-MM-DD.
label label string — What the board is called. Without one it is announced as "Task board".
laneBy lane-by BmxBoardLaneBy 'none' What the rows of the board are: none, assignee, category or parent (the phase).
links links BmxTaskLink[] | string [] The links between tasks, which decide each card's dates and whether it is critical.
locale locale string — The locale dates are written in. Defaults to the page's.
projectStart project-start string — The first day work can happen, YYYY-MM-DD.
showDates show-dates boolean true Shows each card's dates.
strictLimits strict-limits boolean false Refuses a card to a column that is at its limit.
tasks tasks BmxTask[] | string [] The tasks - the same list bmx-gantt takes. Summaries are not cards.
workingDays working-days number[] | string [1, 2, 3, 4, 5] Days of the week that are worked, 0 for Sunday.

Events

EventDetailDescription
bmxCardMove BmxTaskBoardMoveDetail A card is about to move. Cancelable.
bmxSelect BmxTaskBoardSelectDetail A card was chosen.

Methods

MethodSignatureDescription
focusCard focusCard(id: string) => Promise<void> Focuses a card.
getSchedule getSchedule() => Promise<BmxSchedule> The plan as scheduled.
moveCard moveCard(id: string, column: string, lane?: string, index?: number) => Promise<boolean> Moves a card from script, as if the reader had; returns whether it moved.

Slots

SlotDescription
empty what to draw when there are no tasks.

CSS shadow parts

PartDescription
board
card-assignee
card-category
card-critical-badge
card-dates
card-ghost
card-name
card-progress
card-wbs
column-count
empty
lane
lane-header
placeholder

CSS custom properties

PropertyDescription
--bmx-board-card-background A card's fill.
--bmx-board-card-border Its border.
--bmx-board-card-color Its text.
--bmx-board-card-radius Its corners.
--bmx-board-card-shadow Its shadow.
--bmx-board-column-background A column's fill.
--bmx-board-column-width The narrowest a column may be.
--bmx-board-columns How many columns there are. Written by the component.
--bmx-board-critical-color The mark on a critical card.
--bmx-board-header-color Column and lane headings.
--bmx-board-over-color A column's count once it passes its limit.
--bmx-board-progress-color The progress meter.
--bmx-board-target-color The outline of the cell a card would land in. @part board - the whole board (role="region"). @part column-header - a column's heading. Also column-header-over. @part column-count - its count, against its limit when it has one. @part lane - one row of the board. @part lane-header - a lane's heading. @part cell - one lane-and-column cell (role="list"). Also cell-target. @part card - one card. Also card-critical, card-carried and card-<category>. @part card-wbs - the outline number. @part card-category - the category chip. @part card-critical-badge - the "Critical" chip. @part card-name - the task's name. @part card-dates - its dates. @part card-assignee - the assignee's initials. @part card-progress - the progress meter. @part placeholder - where a dragged card would land. @part card-ghost - the copy that follows the pointer. @part empty - what is drawn when there are no tasks.

<bmx-textarea>

Properties

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
description Rich help text, in place of the description property.
label Rich label content, in place of the label property.

CSS shadow parts

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
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

MethodSignatureDescription
hide hide() => Promise<void> Hide it, whatever it is currently doing.
show show() => Promise<void> Show it.

Slots

SlotDescription
(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

PartDescription
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

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxSelect BmxToolbarSelectDetail Fired when an item is chosen from the overflow menu.

Methods

MethodSignatureDescription
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

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

CSS shadow parts

PartDescription
base The bar.
menu The overflow menu's surface.
trigger The overflow button.

CSS custom properties

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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

EventDetailDescription
bmxOpenChange boolean Fired when it opens or closes, with true or false.

Methods

MethodSignatureDescription
hideTooltip hideTooltip() => Promise<void> Hide it now.
showTooltip showTooltip() => Promise<void> Show it now, whatever the delays say.

Slots

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

CSS shadow parts

PartDescription
arrow The pointer drawn against the anchor.
surface The floating box.

CSS custom properties

PropertyDescription
--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

PropertyAttributeTypeDefaultDescription
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.
prepareFile property only BmxUploadPrepare — Prepares each file before it joins the queue, one at a time: return the file, a changed copy, or null to leave it out. Size and type limits are checked on what it returns. A picture editor fits here: upload.prepareFile = file => editor.editFile(file).
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

EventDetailDescription
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

MethodSignatureDescription
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

SlotDescription
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

PartDescription
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

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