BbSelect

When true, the options panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. When unset, falls back to the global config.adaptive.

Set it per instance only to disagree with the app-wide config.adaptive. If every select in your app should open as a sheet on mobile, set it once in the plugin config instead.

Name of the icon to be added at the end of the input.

Replaces the chevron rather than sitting next to it. v3 removed both the showChevron prop and the #chevron slot; this is what customises the trailing icon.

Guides to the browser as to the type of information expected in the field.

Sets autofocus on page load.

Displays a clear button when the input has a value and is being interacted with.

Sets the display model for selected values to a list of comma separated string. In this mode the user cannot deselect an option by pressing the close button.

A display mode, and it costs the per-value close button: in comma mode a value can only be removed from the panel, and clearable — which empties everything — is the only button left on the field.

Sets the component in a compact mode.

Defines an array of dependencies that will trigger actions in the component upon change.

Compared by value hash, not by reference, so an array rebuilt on every render does not refetch. Coherence is lazy: a select with a provider and an empty model ignores changes here until its first load.

Timeout used to debounce response to changes to dependencies.

Defaults to 0. Raise it when the upstream field changes on every keystroke.

Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via aria-describedby (after any errors / warnings, before the hint).

Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like xx xxxxx.

Disables the component.

Controls whether the search input is shown inside the dropdown panel. true removes it everywhere; 'mobile' / 'desktop' remove it on that platform only; 'auto' removes it when an **array** items renders fewer options than the plugin's autoDisableWritingThreshold (default 6; disabled options count, group headers don't). 'auto' is decided when the panel opens and held until it closes, never applies to a provider (function) items, never when you listen to option:add (a creatable select keeps its field), and is off when the threshold is 0. There is no global switch: hiding or forcing a field is this prop, per instance.

Also the supported way to switch filtering off, and it takes option:add with it — both need a query to exist. It inverts v2's allowWriting, and the old name lands in $attrs silently: :allow-writing="false" becomes disable-writing, allow-writing="not-mobile" becomes disable-writing="mobile".

If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. modelValue will be reset upon incoherence.

Reach for it when items can change under a value that is already selected — a dependent select, or a list reloaded from the server. Without it a stale selection survives and gets submitted.

Can be a string or an array of string containing the messages to display. They render in an aria-live="polite" region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's aria-describedby, so the reason the field is invalid is re-read whenever the control regains focus.

Property paths used to filter options when the user types in the search input. When empty (default) options are matched against their display text. When non-empty the provided paths are searched instead of the display text. To disable filtering entirely set disableWriting so the user cannot type a query.

Replaces the match against the display text rather than adding to it, and every listed path must exist on every item or matching throws. With a provider it still applies, on top of the response — a server match whose text does not contain the query is hidden by this local pass.

Path to item property for grouping options.

Grouping changes how the list virtualises: a flat list windows per row, a grouped list windows per group, so one group with thousands of options mounts in full. Keep such lists flat, or chunk them.

Define if the component should be in an error state. It usually attaches a CSS class for styling purposes.

Define if the component should be in a warning state. Same chrome as errors with --bb-warn; errors take priority.

Height of group headers in the listbox (px). Defaults to 32px (24px compact; 36px / 32px on mobile viewports). Only applies when groupBy is set. An explicit value wins on every viewport.

Defaults to 32px (24px compact, 36px in the mobile sheet). Set it in the prop and not in CSS — the number also feeds the virtualiser, so a stylesheet override desynchronises the paint from the scroll maths.

Visually hides the label of the input while maintaining accessibility.

Text box to be displayed near the input, usually to indicate instructions.

The identifier of the component.

Height of the options in the listbox (px). Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport.

Defaults to 28px (24px compact, 44px in the mobile sheet). Raise it to match taller #option markup; a CSS override moves the paint without moving the scroll maths.

ADDITIONAL row fields resolved from each item — never its text or value (those stay on itemText / itemValue). Accepted fields: - description — a muted line under the option label. Setting it gives every row a fixed two-line height (the list is virtualized); the description stays on one line and ellipsizes. Announced as the option's description, never part of its name; matched by the search with the text when filterBy is empty. - prepend:icon — an icon before the label. - append:icon — an icon after the label; on the selected row the check takes its place. Either an object with a path or getter per field ({ description: 'email', 'prepend:icon': 'icon' }) or a function returning the fields ((item) => ({ description: item.email })). Without it no field renders — nothing is read off the item implicitly — and an empty value renders nothing for that item. Never shown in the trigger or the chips. To disable individual options use selectable.

Used to retrieve items; can be an array or a function.

Pass your domain objects as they are and describe them with item-text and item-value. Pass a function when the list is too large to ship up front; it receives the current query and must resolve to the options for it.

Defines a path that returns a property of the object to use as text or a function that returns a string.

Defines a path that returns a property of the object to use as value or a function that returns any value.

Prefer a primitive id: stable, unique, cheap to submit. Omit it and the whole object becomes the value; matching still uses its value hash, but the model then carries the full object.

Text content of the label of the element.

Label rendering mode.

Sets the text alignment of the label.

Sets the component in a loading state, usually triggering some visual styles.

External pending state only — a parent form saving, say. Fetching through a provider drives its own loading state, so mirroring it here does nothing but hide bugs.

String displayed while items are being loaded.

Maximum number of selectable items when the multiple flag is set.

Applies to multiple only, and defaults to unlimited. At the cap the unselected options disable themselves while the selected ones never do, so a reader who reached the limit can always trade one choice for another.

Maximum number of labels shown before collapsing to a count summary. Unset, the labels collapse only when they overflow the field.

Applies to multiple only. Past the limit the extra selections collapse into a "+N" summary, which is not rendered through the chip slot.

Used by v-model. Can be any serializable type.

Timeout used to debounce response to changes to modelValue.

Allows the selection of multiple items.

The model must already be an array on the first render. A scalar or an unseeded ref() throws at setup rather than guessing.

Defines the name of the input.

Renders one hidden input per value, JSON-stringifying anything that is not a string. In v3 an empty selection posts no field at all, like a native <select multiple> with nothing chosen; v2 posted the literal string "null".

String displayed when there are no items to display.

Props for the phone sheet. A pt inside it, object or colon keys, styles only that sheet. Extra props forwarded to the BbOffCanvas sheet when adaptive is active on mobile. A pt inside it styles ONLY the sheet, in BbOffCanvas's part words (root, header, title, description, content, footer, close; state open), object ({ pt: { header: '…' } }) or colon keys ({ 'pt:header': '…' }) alike. It merges after what this component forwards to its sheet, so it wins a conflict and drops nothing — see the passthrough guide § Inside the sheet.

Keeps the hint displayed.

String displayed when there's no data.

Single mode only. An empty multiple select renders nothing, so put its guidance in description or hint.

Controls when items are pre-loaded. 'interaction' loads on the first user interaction, true loads immediately on mount, false is *search-first*: with a provider, nothing is fetched until the user types — opening alone does not load, and the panel shows a "search to begin" hint meanwhile. false falls back to loading on open when the user could not otherwise reach the options: array items (resolved on mount regardless), or disable-writing (no search field to type into). When the input has a value, it always loads immediately so the selection's text can render.

Defaults to 'interaction'. false is search-first — nothing loads until the user types — which is a change of meaning from v2, where it meant "load on first open"; that is now the default. Array items and a non-empty model both load regardless, and a null "All" option counts as empty, so it needs prefill: true to resolve.

Name of the icon to be added at the start of the input.

Passthrough, object form: the same keys as the pt:* attributes without the prefix. See the pt:<part> row.

Time to wait when the user stops writing in the input before querying data.

Defaults to 500ms. The component owns the debounce; a hand-rolled one around the provider fights it.

Sets the input in a readonly state.

Sets the input as required.

Marks the field and feeds the asterisk, but does not trigger native constraint validation: the hidden inputs carrying the value are barred from it by the HTML spec. The message a reader sees still comes from errors.

Reverses the layout. Applicable in every direction the order of the label and the input is swapped.

Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled.

The only supported way to disable individual options. A disabled field on the item object is inert domain data in v3 — feed it to the predicate instead, or filter the row out of items.

Function that returns a string to be displayed when the number of selected labels is greater than maxSelectedLabels.

Adds a stash to accumulate selected values across searches.

Keeps every previously fetched option resolvable, which is what stops a chip losing its text after a later search. The flip side: on a select with dependencies it also keeps stale picks coherent, so enforceCoherence will never prune them.

How long the transition has to last in milliseconds.

Visual variant of the field box — the same names and tokens as the BbButton variants. Colours only: height, padding and border width are identical across variants, so a form never reflows when one changes. 'ghost' has no border in any state (errors and warnings show through the icon and the messages); every variant keeps the focus ring. Register extra names with the plugin's inputVariants option.

Warning messages to display beneath the field, in their own aria-live region and amber (--bb-text-warn). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also referenced from the control's aria-describedby, after any errors and before the description/hint.

Holds a single value, or an array of them under multiple. Its shape follows item-value: ids when you set one, whole objects when you do not.

Emitted once the options surface has finished closing.

Emitted as soon as the options surface starts to close.

Validate on this, not on blur. Focus legitimately moves into the panel while the reader is choosing, so blur fires mid-interaction; inactive fires when focus has left both the control and the panel.

Fires when the user commits an option the list did not contain. Use it to create the record on your side, then push it into items so the selection resolves. It can fire with an empty string, and disableWriting removes it along with the search field.

Emitted as soon as the options surface starts to open (the popover, or the sheet on a phone).

Emitted once the options surface is open and its open transition has finished.

Content appended inside the input field, after the value area.

Content appended outside the input field wrapper.

Replaces the default badge rendered for each selection in multiple mode. Not called in comma mode, nor for the collapsed "+N" summary.

Replaces the badge for each selection in multiple mode. It is not called in comma mode, nor for the collapsed "+N" summary, so keep the two presentations recognisably the same.

Replaces the description text. Provided alone (no description prop) it still renders the description region and wires it into aria-describedby.

Content pinned to the bottom of the options panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.

Renders below the options list in the desktop popover and in the mobile sheet alike. Select-all lives here: the model is yours, so assigning every value to it is the whole implementation.

Replaces the default group header rendered above grouped options.

Styles the group header only. length is the size of the group and index the list position of its first option.

Content pinned to the top of the options panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.

Renders above the search field. Derive any summary from your own model rather than from selectedOptions, which resolves against loaded options and is empty until a provider first runs.

Replaces the default label text rendered above the input.

Content shown inside the options dropdown while items are loading.

Content shown when no options match the query or the list is empty.

Replaces the default rendering of each option row in the dropdown.

Replaces the row's text, not the selection check — that renders outside the slot and survives any markup. Taller rows need itemHeight to match.

Content rendered as an inline prefix inside the input field.

Content prepended inside the input field, before the value area.

Content prepended outside the input field wrapper.

Content rendered as an inline suffix inside the input field.