Button

Buttons trigger actions in the current context — saving, submitting, confirming, or moving forward in a flow. Use emphasis to communicate priority: each view should have one clear primary action, while secondary actions should be visually lower in emphasis.

Use a link button for navigation when the intent is to move to another page. See the Link variant.

When to use

Use buttons when

The user is taking an action in the current context
The action changes data, state, or progress
The action needs clear visual priority

Do not use buttons when

An ordinary text link is enough for navigation
Several actions compete for equal importance

Use bq-dropdown to open a list of related actions or destinations; a bq-button can be its trigger. Use bq-button on its own for one action. For navigation, set href so the button renders as a link.

Button patterns

Some patterns below are standalone bq-button usages, while others are composite interactions built from buttons and related components.

A standard button initiates a single action or event.

Menu Button

Toggles a menu of options without surfacing a primary action.

Split Button

Lets someone take one of several related actions. The dominant action is the label; alternatives are in a menu.

Icon Only

The most compact type, used for supplementary actions like “Bookmark” or “Star.”

Segmented Button

Helps people select options, switch views, or sort elements.

Floating Button

Floating action buttons (FABs) help people take primary actions.

Anatomy

A button can contain a label and optional leading or trailing icons. The label should always communicate the action clearly. Icons should reinforce meaning, not replace it — unless the action is universally understood and an accessible label prop is provided.

Part	Element	Description
1	Container	The interactive surface wrapping all content
2	Icon	Optional `prefix` or `suffix` slot content
3	Label	The primary communicator of the action

Design guidelines

Choose the button variant based on the importance of the action. Use the strongest visual treatment for the main action in a region. Labels should be short and specific, and several actions should not compete for the same level of emphasis.

Usage

appearance defines the base style of the button. variant modifies supported appearances — ghost applies to both primary and secondary buttons, while danger is reserved for destructive actions on the primary appearance.

Dimension	Allowed values	Default
`appearance`	`primary`, `secondary`, `link`, `text`	`primary`
`variant`	`standard`, `ghost`, `danger` (applies to `appearance="primary"` only)	`standard`
`size`	`small`, `medium`, `large`	`medium`
`border`	`none`, `xs2`, `xs`, `s`, `m`, `l`, `full`	`m`
`type`	`button`, `submit`, `reset`	`button`
`justify-content`	`left`, `center`, `right`	`center`
`target` (only with `href`)	`_blank`, `_parent`, `_self`, `_top`	none

Primary

The highest priority action in a view. Only one per screen or section.

You don’t need to specify any property that uses its default value. The default appearance is primary with variant standard.

Primary also supports ghost and danger variants:

Danger: reserved for actions that may result in critical or irreversible consequences, such as deleting important data or confirming a high-risk operation.
Ghost: a more subtle style for secondary or less prominent actions that don’t require immediate attention.

Secondary

Lower-emphasis actions. Can stand alone or pair with a primary button to perform secondary actions. Supports the ghost variant.

Link

Renders as an <a> element under the hood when href is provided. Still action-oriented, not for plain navigation.

When using the Link button, always provide a href value.

Text

No background or border. Suitable for inline actions, subtle calls to action, or options within a form.

Options

Size and shape

Sizes

Choose the size that best matches the context. Medium is the default and should be the size for most interfaces. Allowed size values: small, medium (default), large.

Size	When to use
Small	When space is limited or the action is less significant
Medium	Default — suitable for most interfaces
Large	To increase the significance of an action; use sparingly

Full width

Use the block attribute to make the button stretch to its parent width.

Border radius

Use the border property to control the corner radius. Allowed border values: none, xs2, xs, s, m (default), l, full.

States

For each button appearance and variant, there are six visual states: enabled, hover, focus, active, loading and disabled.

Disabled

The disabled attribute can be applied to any button variation. When disabled, no interaction is allowed and the bqClick event won’t fire.

Avoid disabled buttons when possible. If an action is unavailable, prefer keeping the button discoverable and explain what is required to proceed.

Loading

Use the loading attribute to indicate something is being processed. Pair with disabled to prevent duplicate actions.

Icons

Leading and trailing icons

Use the prefix or suffix slot to add icons. Icons should reinforce the label — never use them for decoration only.

Only-icon buttons

Use only-icon buttons only for common, easily recognized actions. Always provide a label so assistive technologies can announce the action correctly.

Do not use prefix or suffix slots for icon-only buttons. Pass the icon as the default slot and always set the label prop.

Content guidelines

Label guidelines

Guideline	Rule
Be concise	Labels should be 1–2 words, max 4 words, under 20 characters. Labels should not include punctuation.
Use verbs	Labels should describe the action: “Save”, “Delete”, “Submit” — not nouns or adjectives.
Sentence case	Labels should not use ALL CAPS to emphasize a button.
No wrapping	Labels must not break to multiple lines.
No emoji	Labels should be functional and utilitarian. Labels should not include emoji or exclamation points.

Best practices

DoKeep button labels succinct — 1 or 2 words, no longer than 4, under 20 characters.

Don’tNever let button labels wrap to multiple lines or lose their button shape.

DoPair a primary button with a secondary button for alternative actions.

Don’tDon’t place multiple primary buttons together — it dilutes the visual hierarchy.

DoKeep emphasis aligned with task priority — one primary action per view.

Don’tDon’t use icons as decoration. Every icon should reinforce the label meaning.

DoUse icon-only buttons only when the action is familiar and the label prop provides an accessible name.

Don’tDo not rely on an icon alone when the action is uncommon, destructive, or easy to misunderstand.

Accessibility

Use descriptive labels — buttons must have descriptive labels so users know what will happen, which reduces errors and increases confidence.
Icon-only buttons — you must set the label prop to provide a text alternative for assistive technologies.
Disabled states — disabled sets aria-disabled="true", removes the control from the Tab order, and prevents activation. Native buttons also receive disabled. Disabled controls are not necessarily hidden from screen readers; you should explain nearby what is required to proceed.
Correct semantics — you must omit href for actions and set href for navigation. appearance="link" changes styling only; it does not turn a button into a link.

Keyboard interaction

The component renders a native button, or a native a when href is set.

Key	Context	Action
`Tab`	Any	Moves focus to the next enabled button; a disabled button has `tabindex="-1"` and is skipped
`Shift` + `Tab`	Any	Moves focus to the previous enabled button
`Enter`	Button or link focused	Emits `bqClick`; with `type="submit"` or `type="reset"` it submits or resets the associated form; with `href` it follows the link
`Space`	Button focused (no `href`)	Emits `bqClick`; with `type="submit"` or `type="reset"` it submits or resets the associated form

A disabled or loading button does not emit bqClick or act on the form. Space does not activate a link rendered with href.

Rules

Rule	Strength	Verified by
Give every button a descriptive label	MUST	manual: compare the visible label with the action it performs
Set `label` on icon-only buttons	MUST	manual: inspect the button’s accessible name
Omit `href` for actions and set `href` for navigation; `appearance="link"` changes styling only	MUST	manual: inspect whether the rendered element is a button or link
Explain nearby why a button is `disabled`, since disabled controls are not necessarily hidden from screen readers	SHOULD	manual: review the explanation beside each disabled button

API reference

Properties

Property	Attribute	Description	Type	Default
`appearance`	`appearance`	The appearance style to apply to the button	`'primary'` \| `'secondary'` \| `'link'` \| `'text'`	`'primary'`
`block`	`block`	If `true`, makes the button fit to its parent width	`boolean`	`false`
`border`	`border`	The corner radius of the button	`'none'` \| `'xs2'` \| `'xs'` \| `'s'` \| `'m'` \| `'l'` \| `'full'`	`'m'`
`disabled`	`disabled`	If `true`, the button will be disabled	`boolean`	`false`
`download`	`download`	Tells the browser to treat the linked URL as a download. Only used when `href` is set	`string`	`undefined`
`href`	`href`	When set, renders an `<a>` instead of a `<button>`	`string`	`undefined`
`justifyContent`	`justify-content`	How the content should be aligned	`'left'` \| `'center'` \| `'right'`	`'center'`
`label`	`label`	Accessible label for screen readers, especially for icon-only buttons	`string`	`undefined`
`loading`	`loading`	If `true`, displays the button in a loading state	`boolean`	`false`
`onlyIcon`	`only-icon`	If `true`, renders the button as icon-only with 1:1 aspect ratio	`boolean`	`false`
`size`	`size`	The size of the button	`'small'` \| `'medium'` \| `'large'`	`'medium'`
`target`	`target`	Where to display the linked URL	`'_blank'` \| `'_parent'` \| `'_self'` \| `'_top'`	`undefined`
`type`	`type`	The default behavior of the button	`'button'` \| `'submit'` \| `'reset'`	`'button'`
`variant`	`variant`	The variant on top of appearance (primary and secondary only)	`'standard'` \| `'ghost'` \| `'danger'`	`'standard'`

Invalid combinations

Combination	Strength	Result
`only-icon` without `label`	MUST NOT	The component logs a console warning because the icon-only button has no accessible name
`download` without `href`	SHOULD NOT	`download` is dropped because the button renders a `<button>` instead of a link

Events

Event	Description	Type
`bqBlur`	Fires when the button loses focus	`CustomEvent<HTMLBqButtonElement>`
`bqFocus`	Fires when the button receives focus	`CustomEvent<HTMLBqButtonElement>`
`bqClick`	Fires when the button is clicked. Cancelable: on a button with `href`, calling `event.preventDefault()` stops the link navigation, so a client-side router can take over	`CustomEvent<HTMLBqButtonElement>`

In React, prefix events with on: onBqClick, onBqFocus, onBqBlur.
In Angular, use the event binding syntax: (bqClick), (bqFocus), (bqBlur).
In Vue, use the @ shorthand: @bqClick, @bqFocus, @bqBlur.

Slots

Slot	Description
(default)	The button label content
`prefix`	Content displayed before the button label
`suffix`	Content displayed after the button label

Shadow parts

Part	Description
`button`	The native `<button>` or `<a>` element
`label`	The `<span>` rendering the button text
`prefix`	The prefix container
`suffix`	The suffix container

CSS custom properties

Hide CSS variables

Variable	Description	Default
`--bq-button--border-color`	Border color	`transparent`
`--bq-button--border-radius`	Border radius	`var(--bq-radius--m)`
`--bq-button--border-style`	Border style	`solid`
`--bq-button--border-width`	Border width	`var(--bq-stroke-m)`
`--bq-button--small-paddingX`	Small size padding inline	`var(--bq-spacing-xs)`
`--bq-button--small-paddingY`	Small size padding block	`calc(var(--bq-spacing-xs2) - var(--bq-button--border-width))`
`--bq-button--small-font-size`	Small size font size	`var(--bq-font-size--m)`
`--bq-button--medium-paddingX`	Medium size padding inline	`var(--bq-spacing-m)`
`--bq-button--medium-paddingY`	Medium size padding block	`calc(var(--bq-spacing-s) - var(--bq-button--border-width))`
`--bq-button--medium-font-size`	Medium size font size	`var(--bq-font-size--m)`
`--bq-button--large-paddingX`	Large size padding inline	`var(--bq-spacing-l)`
`--bq-button--large-paddingY`	Large size padding block	`calc(var(--bq-spacing-m) - var(--bq-button--border-width))`
`--bq-button--large-font-size`	Large size font size	`var(--bq-font-size--m)`
`--bq-button--primary-background`	Primary button background color	`var(--bq-ui--brand)`
`--bq-button--primary-text-color`	Primary button text color	`var(--bq-text--on-brand)`
`--bq-button--primary-border-color-ghost`	Primary ghost button border color	`var(--bq-stroke--brand)`
`--bq-button--primary-text-color-ghost`	Primary ghost button text color	`var(--bq-text--brand)`
`--bq-button--primary-background-danger`	Primary danger button background color	`var(--bq-ui--danger)`
`--bq-button--primary-text-color-danger`	Primary danger button text color	`var(--bq-text--on-danger)`
`--bq-button--secondary-background`	Secondary button background color	`var(--bq-ui--secondary)`
`--bq-button--secondary-text-color`	Secondary button text color	`var(--bq-text--primary)`
`--bq-button--secondary-border-color-ghost`	Secondary ghost button border color	`var(--bq-stroke--tertiary)`
`--bq-button--secondary-text-color-ghost`	Secondary ghost button text color	`var(--bq-text--primary)`
`--bq-button--link-text-color`	Link button text color	`var(--bq-text--brand)`
`--bq-button--text-text-color`	Text button text color	`var(--bq-text--primary)`

Learn more about styling with shadow parts and CSS custom properties.

Resources

Interactive playground

Explore all button configurations in Storybook

Source code

View the component source on GitHub

​When to use

​Button patterns

Button

Menu Button

Split Button

Icon Only

Segmented Button

Floating Button

​Anatomy

​Design guidelines

​Usage

​Primary

​Secondary

​Link

​Text

​Options

​Size and shape

​Sizes

​Full width

​Border radius

​States

​Disabled

​Loading

​Icons

​Leading and trailing icons

​Only-icon buttons

​Content guidelines

​Label guidelines

​Best practices

​Accessibility

​Keyboard interaction

​Rules

​API reference

​Properties

​Invalid combinations

​Events

​Slots

​Shadow parts

​CSS custom properties

​Resources

Interactive playground

Source code

When to use

Button patterns

Anatomy

Design guidelines

Usage

Primary

Secondary

Link

Text

Options

Size and shape

Sizes

Full width

Border radius

States

Disabled

Loading

Icons

Leading and trailing icons

Only-icon buttons

Content guidelines

Label guidelines

Best practices

Accessibility

Keyboard interaction

Rules

API reference

Properties

Invalid combinations

Events

Slots

Shadow parts

CSS custom properties

Resources