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

The user is navigating to another page with no side-effect
Several actions compete for equal importance
A text link is sufficient

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, keep labels short and specific, and avoid making several actions 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.

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 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 preferred size for most interfaces.

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.

States

For each button appearance and variant, there are five 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.

Icon-only buttons

Use icon-only 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	1–2 words, max 4 words, under 20 characters. No punctuation.
Use verbs	Labels should describe the action: “Save”, “Delete”, “Submit” — not nouns or adjectives.
Sentence case	Never use ALL CAPS to emphasize a button.
No wrapping	Labels must never break to multiple lines.
No emoji	Keep labels functional and utilitarian. No 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 — labeling buttons properly lets users know what will happen, reduces errors, and increases confidence.
Icon-only buttons — always set the label prop to provide a text alternative for assistive technologies.
Keyboard navigation — buttons are focusable and activated with Enter or Space by default.
Avoid disabled states — disabled buttons are invisible to screen readers. Where possible, keep the button discoverable and explain what is required to proceed.
Correct semantics — use <bq-button> for actions and links for navigation.

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'`

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	`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	`0`
`--bq-button--small-paddingX`	Small size padding block	`var(--bq-spacing-xs)`
`--bq-button--small-paddingY`	Small size padding inline	`var(--bq-spacing-xs2)`
`--bq-button--small-font-size`	Small size font size	`var(--bq-font-size--m)`
`--bq-button--medium-paddingX`	Medium size padding block	`var(--bq-spacing-m)`
`--bq-button--medium-paddingY`	Medium size padding inline	`var(--bq-spacing-s)`
`--bq-button--medium-font-size`	Medium size font size	`var(--bq-font-size--m)`
`--bq-button--large-paddingX`	Large size padding block	`var(--bq-spacing-l)`
`--bq-button--large-paddingY`	Large size padding inline	`var(--bq-spacing-m)`
`--bq-button--large-font-size`	Large size font size	`var(--bq-font-size--m)`

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

​Icon-only buttons

​Content guidelines

​Label guidelines

​Best practices

​Accessibility

​API reference

​Properties

​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

Icon-only buttons

Content guidelines

Label guidelines

Best practices

Accessibility

API reference

Properties

Events

Slots

Shadow parts

CSS custom properties

Resources