Skip to main content
This page covers the three techniques you reach for when customizing a specific component: shadow DOM parts, global token overrides, and component-level CSS variables. For building a full custom theme or understanding the complete token system, see the Theming section.
The examples use inline <style> tags so you can run them directly. In a real project, place these overrides in your own stylesheet.

​
Component shadow DOM parts

Shadow DOM keeps a component’s internal structure insulated from the surrounding page styles. BEEQ exposes named internal sections — called parts — so you can still target them with CSS from the outside. For example, bq-button exposes its button wrapper and label as separate parts: 
<!-- bq-button.tsx -->
<button part="button">
  <span class="bq-button__label" part="label">
    <slot />
  </span>
</button>
Style them using the ::part() pseudo-element from your own stylesheet:

​
Inspecting parts from JavaScript

Parts are also queryable from JavaScript when you need to reach into component internals programmatically: 
const bqButton = document.querySelector(".custom-button");
const nativeButton = bqButton?.shadowRoot?.querySelector('[part="button"]');

​
Global CSS custom properties

BEEQ relies on CSS custom properties to maintain a consistent visual system across components. A single global token like --bq-brand cascades through colours, focus rings, borders, and related states — so overriding it at the root level changes the look of your whole product at once: 
:root {
  --bq-brand: var(--bq-orange-600);
}

​
Component-level CSS custom properties

Component-level CSS variables are scoped to a single component instance and do not affect the rest of the theme. For a full explanation of override strategies — including how to apply changes across all instances of a component at once — see Component CSS Variables. In the example below, the second button overrides one brand token locally while the first keeps the theme default: Some components also expose CSS variables that scope to that component only — not global tokens. You’ll find them listed in each component’s API reference under CSS custom properties.

​
Combining component variables and parts

Combine component CSS variables and ::part() selectors when token overrides alone aren’t enough — you get scoped sizing control and structural styling from a single class.

​
Where to find component styling hooks

Not every component exposes the same CSS variables or parts. When a component does expose them, you can find them in:
  • the component page’s API reference
  • the component source in GitHub under packages/beeq/src/components/**/scss/*.variables.scss

​
Best practices

Start with global tokens

When a change should apply across the whole product, override a global token like --bq-brand. One change cascades through every component that derives from it.

Avoid per-component overrides for global decisions

Repeating the same CSS variable on every component instance makes the theme harder to update and easy to get out of sync.

Scope one-off overrides with a class

Use a specific class selector so your override only applies where you intend it — not to every instance of the component on the page.

Avoid broad selectors for local overrides

Targeting bq-button or :root for a one-off change affects every instance globally. Scope exceptions with a class.

Reach for `::part()` when variables aren't enough

Shadow DOM parts give you structural access to component internals. Use them when the exposed CSS variables don’t cover what you need.

Don't use `::part()` as your first tool

::part() couples your styles to component internals. If a CSS variable covers the change, prefer that — it’s less likely to break across BEEQ updates.

Check both light and dark modes

Review your overrides in both colour modes to make sure contrast, hierarchy, and focus states still hold up.

Don't verify only one colour mode

Overrides that look correct in light mode often break contrast or colour hierarchy in dark mode.