BbCollapsible

Use it for

Reach for BbCollapsible when the trigger cannot be a header sitting over the body. A switch in a settings row, a "Show more" at the end of a paragraph, a button in a toolbar.

Use something else when

BbAccordion, if the trigger is a title over the body: it writes the button and the ARIA for you
BbSmoothHeight, if you hide nothing and only want a height change to animate
BbTabs, if they are peer views of one subject and only one stays visible

BbAccordion is this component plus a wired header button. Everything on this page is true there too.

Ships from Turin in two working days.

Default

Bind a boolean and supply the control that flips it.

<template>
	<div class="flex max-w-md flex-col items-start gap-2">
		<!--
			The trigger is yours, and so is its ARIA: `aria-expanded` says whether
			the region is open, `aria-controls` says which region it is.
		-->
		<BbButton
			aria-controls="collapsible-basic-panel"
			:aria-expanded="open"
			:append:icon="open ? 'lucide:chevron-up' : 'lucide:chevron-down'"
			prepend:icon="lucide:settings-2"
			variant="outline"
			@click="open = !open"
		>
			Advanced options
		</BbButton>

		<!-- One-way on purpose: the component renders `open`, it never writes it. -->
		<BbCollapsible id="collapsible-basic-panel" :model-value="open">
			<div class="grid gap-3 pt-3">
				<BbNumberInput
					id="collapsible-basic-retries"
					v-model="retries"
					compact
					label="Retry attempts"
					:max="10"
					:min="0"
					name="retries"
				/>
				<BbSwitch
					id="collapsible-basic-signature"
					v-model="signed"
					label="Sign the payload"
					name="signed"
				/>
			</div>
		</BbCollapsible>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCollapsible, BbNumberInput, BbSwitch } from 'bitboss-ui';

// Initialise the boolean. `model-value` defaults to `false` and there is no
// event to listen to: every change comes from the trigger above.
const open = ref(false);

const retries = ref<number | null>(3);
const signed = ref(true);
</script>

The component cannot open or close itself. It renders model-value and never writes it back, and it emits nothing. v-model compiles and works, but only as a prop binding, so do not wait for an update:modelValue. Put side effects on the trigger.

model-value is optional and defaults to false: a missing or undefined binding renders closed. Initialise the ref with ref(false).

The root is a div, for block content (fields, paragraphs, lists), as every demo on this page holds. Pass tag="span" for a collapsible that sits inside a paragraph.

You own the trigger

The component manages the region. The semantics of the control that opens it are yours.

If the trigger is a button, give it aria-expanded and aria-controls pointing at the collapsible's id. Without them a screen-reader user gets a button whose effect is announced nowhere. That is what the Default demo above wires. bitboss-ui check reports a click handler that flips the ref with no aria-expanded on the trigger.

When the trigger is already a control with a state, do not add a second one:

Use a custom domain

Hostname

CNAME target

<template>
	<div class="flex max-w-md flex-col gap-2">
		<!--
			No `aria-expanded` here: the switch's own checked state already says
			whether the dependent fields are in play. Adding it would announce the
			same fact twice, in two vocabularies.
		-->
		<BbSwitch
			id="collapsible-switch-custom-domain"
			v-model="customDomain"
			label="Use a custom domain"
			name="customDomain"
		/>

		<BbCollapsible :model-value="customDomain">
			<div class="grid gap-3 pt-3">
				<BbTextInput
					id="collapsible-switch-host"
					v-model="host"
					compact
					label="Hostname"
					name="host"
					placeholder="app.example.com"
				/>
				<BbTextInput
					id="collapsible-switch-cname"
					v-model="cname"
					compact
					label="CNAME target"
					name="cname"
				/>
			</div>
		</BbCollapsible>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbCollapsible, BbSwitch, BbTextInput } from 'bitboss-ui';

// One ref drives the switch and the region. Turning the option on reveals the
// fields it needs; there is nothing else to wire.
const customDomain = ref(true);

const host = ref<string | null>('shop.northwind.io');
const cname = ref<string | null>('edge.bitboss.io');
</script>

A switch or a checkbox bound to the same ref already says "on / off", and the fields that appear are the consequence of the setting. Adding aria-expanded there announces the same fact twice.

If you would rather not wire this, step up to BbAccordion: it writes the header button for you.

Closed content is out of reach

Hiding something visually is not hiding it. Here the component does that work.

No refund requested yet.

<template>
	<div class="flex max-w-md flex-col items-start gap-2">
		<BbButton
			aria-controls="collapsible-inert-panel"
			:aria-expanded="open"
			:append:icon="open ? 'lucide:chevron-up' : 'lucide:chevron-down'"
			variant="outline"
			@click="open = !open"
		>
			Refund policy
		</BbButton>

		<!--
			`eager` renders the body immediately, so this text is in the static HTML
			before anyone opens the panel. It still cannot be reached while closed:
			the component marks it aria-hidden and inert.
		-->
		<BbCollapsible
			id="collapsible-inert-panel"
			eager
			:model-value="open"
		>
			<div class="flex flex-col items-start gap-3 pt-3 text-sm">
				<p class="m-0">
					Unopened orders can be returned within 30 days of delivery. Refunds
					reach the original payment method in 5 to 7 working days.
				</p>
				<BbButton
					:disabled="requested"
					size="sm"
					variant="outline"
					@click="requested = true"
				>
					Request a refund
				</BbButton>
			</div>
		</BbCollapsible>

		<p class="m-0 text-sm text-[color:var(--bb-text-muted)]" role="status">
			{{ requested ? 'Refund requested for ORD-2026-0417.' : 'No refund requested yet.' }}
		</p>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCollapsible } from 'bitboss-ui';

const open = ref(false);
const requested = ref(false);
</script>

Closed content is aria-hidden and inert: unfocusable, unclickable, out of the tab order and out of the accessibility tree. Do not wrap it in a v-if: that would take the animation and the mounted state with it.

Nothing inside the slot renders until the first open, and it stays mounted from then on. eager renders it immediately. Reach for it when the content has to exist before anyone opens the region. A form field that must register and validate, text a prerendered page has to carry, anything measured on mount. The demo above is eager, which is why its text sits in this page's static HTML.

One region at a time

Several collapsibles become an exclusive group when you derive each state from one key.

Order ORD-2026-0418

€338.80

Note for the warehouse

<template>
	<div class="flex max-w-md flex-col">
		<div class="flex items-baseline justify-between gap-3">
			<p class="m-0 text-sm font-medium">Order {{ order.reference }}</p>
			<p class="m-0 text-sm tabular-nums text-[color:var(--bb-text-muted)]">
				€{{ order.total.toFixed(2) }}
			</p>
		</div>

		<!-- Actions, not views: nothing has to be open, and each button says
		     which region it opens. -->
		<div class="flex flex-wrap gap-1.5 pt-3">
			<BbButton
				v-for="action in actions"
				:key="action.key"
				:aria-controls="`collapsible-group-${action.key}`"
				:aria-expanded="active === action.key"
				:prepend:icon="action.icon"
				size="sm"
				:variant="active === action.key ? 'secondary' : 'outline'"
				@click="toggle(action.key)"
			>
				{{ action.label }}
			</BbButton>
		</div>

		<!-- No gap around the regions: a closed one still counts as a flex or
		     grid item, so a gap would leave empty space for each. Space the
		     content instead. -->
		<BbCollapsible
			v-for="action in actions"
			:id="`collapsible-group-${action.key}`"
			:key="action.key"
			:model-value="active === action.key"
		>
			<div class="pt-3">
				<BbTextInput
					:id="`collapsible-group-${action.key}-field`"
					v-model="values[action.key]"
					compact
					:label="action.field"
					:name="action.key"
				/>
			</div>
		</BbCollapsible>
	</div>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import { BbButton, BbCollapsible, BbTextInput } from 'bitboss-ui';
import { orders } from '~/demo-data';

type ActionKey = 'note' | 'discount' | 'gift';

const order = orders[1]!;

const actions: Array<{ key: ActionKey; label: string; icon: string; field: string }> = [
	{ key: 'note', label: 'Add note', icon: 'lucide:sticky-note', field: 'Note for the warehouse' },
	{ key: 'discount', label: 'Discount', icon: 'lucide:percent', field: 'Discount code' },
	{ key: 'gift', label: 'Gift message', icon: 'lucide:gift', field: 'Message on the card' },
];

const values = reactive<Record<ActionKey, string | null>>({
	note: 'Leave at the loading bay, gate B.',
	discount: null,
	gift: null,
});

// One active key, every model derived from it. Clicking the open action closes
// it, which is why the key accepts null.
const active = ref<ActionKey | null>('note');

function toggle(key: ActionKey) {
	active.value = active.value === key ? null : key;
}
</script>

One ref holds the open key, each region compares against it, and each trigger assigns it. No group wrapper, and no watcher forcing siblings shut. Make the key nullable if clicking the open trigger should close everything.

When the triggers are stacked headers, you are describing an accordion: see One panel at a time. When one region must always show, the buttons are a tab strip: use BbTabs.

Spacing and timing

Do not pad the collapsible itself: padding on its root stays when it closes, so a closed region keeps that height.

Its inner .bb-collapsible__content (pt:content) loses its vertical padding, border and gap only while closed. Space the element you slot in, as every demo here does. Both parts take an open state, pt:root:open and pt:content:open, for styling that should apply only while the region shows.

transition-duration (milliseconds, 250 by default) drives the height animation and the opacity fade together. Under prefers-reduced-motion: reduce both drop to near-instant.

Coming from v2tag narrowed

tag takes only 'div' (the default) or 'span'. A span root keeps an inline "Show more" valid inside a paragraph. If you passed tag="section", wrap the component instead.

diff

- <BbCollapsible v-model="open" tag="section">…</BbCollapsible>
+ <section>
+   <BbCollapsible v-model="open">…</BbCollapsible>
+ </section>

Three classes are yours: .bb-collapsible on the root, with .bb-collapsible--open / .bb-collapsible--closed tracking the state, and .bb-collapsible__content on the wrapper around your slot. Style the state modifiers, not the animation: the height is a grid-template-rows transition between 0fr and 1fr, and overriding it is how you lose the collapse.