Skip to content

Renders hierarchical expandable tree structures.

import { BbTree } from 'bitboss-ui';

On this page

Props

NameTypeDefaultDescription
expandableBbTreeExpandable<Meta> | undefined-

Defines nodes as expandable. It can be a global boolean, or a function that receives the node, its depth, and its parent and returns a boolean.

Without it nothing is expandable: the tree renders fully expanded and static, which is the answer to "my chevrons do nothing". The everyday form is (node) => !!node.children?.length; a per-node expandable field overrides it for that node, and false on a branch renders its children frozen open rather than hiding them.

See example
expandedItemsany[] | undefined[]

Live expansion state: the list of expanded node values (see itemValue). Branch nodes not explicitly collapsed via expanded: false seed the list when they first appear in items; from then on this model is the single source of truth.

itemsrequiredBbTreeItem<Meta>[][]

Tree-like structure of nodes to render.

Use the fixed { meta, children } envelope. Branches disclose children; leaves render navigation or content from your slot.

See example
itemValueItemAccessor<Meta> | undefinedthe whole `meta` object

Identity of a node, used to hash entries of expandedItems and to name per-node slots. A string reads that key from meta; a function receives meta and returns the value.

Set stable identity before loading remote nodes. Otherwise a refetch can reset expansion and change per-node slot names.

See example
ptPtMap<BbTreePtPart, "open"> | undefined-

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

pt:itemPtValue | undefined-
pt:item:openPtValue | undefined-
pt:rootPtValue | undefined-
pt:root:openPtValue | undefined-

v-model

Values kept in sync through v-model.

NameTypeDescription
expandedItemsany[] | undefined

The live state, and the only way to change expansion from code — pushing a value opens that node, and the expanded flag on an item is ignored after the first sighting. Leaves never appear here, so expand-all is exactly the set of branch identities.

See example

Events

NameTypeDescription
update:expandedItems(event: "update:expandedItems", value: any[]): void

Fires with the whole new list on every toggle. Bind the model and treat it as state rather than listening to this directly.

See example

Slots

The listed properties are the ones exposed to the slot scope.

NameTypeDescription
<depth>BbTreeNodeSlotProps<Meta>

Every node at one depth (0 = root); a numeric value can share this name.

See example
<depth>-childrenBbTreeNodeSlotProps<Meta>

The children container of every node at one depth.

Renders under leaves too, so guard branch-only markup with v-if="item.children?.length".

See example
<value>BbTreeNodeSlotProps<Meta>

One node, by its resolved item-value (string or number) through slotKey; beats <depth>, which beats default.

The name is the identity normalized: src/composables is #src_composables, Order History is #order_history. A stale name raises no warning — the node falls back to <depth> or default.

See example
<value>-childrenBbTreeNodeSlotProps<Meta>

One node's children container, stopping the recursion there; beats <depth>-children. Renders for leaves too.

See example
defaultBbTreeNodeSlotProps<Meta>

Renders every node that no #<value> or #<depth> slot claims. Bind expandProps to a real <button> for branches: it carries aria-expanded and the aria-controls that pairs with the children container, and a button gets focus and Enter/Space for free.

See example