;
};
Each component provides its own CSS custom properties, scoped to that component. This lets you tweak colors, spacing, or other design tokens locally without breaking consistency across the theme. You can find the component CSS variables listed at the bottom of each component documentation page.
For a practical overview of all three customization techniques — shadow DOM parts, global token overrides, and component variables — see [Styles](/guides/styles).
For quick reference, you can also check these variables documented in each component's `scss/*.variables.scss` file on [GitHub](https://github.com/Endava/BEEQ/tree/main/packages/beeq/src/components).
***
## How to override component CSS variables
There are two strategies for customizing a BEEQ component's styles:
Set CSS custom properties on the component element selector to apply changes across **all instances** of a component in your theme.
Use CSS classes or specific component selectors to customize **individual instances** without affecting others.
### Global override
Set CSS custom properties directly on the component selector. This applies the customization to all instances of that component across your entire application.
```css theme={"theme":{"light":"one-light","dark":"night-owl"}}
bq- {
--bq---: value;
}
```
### Targeted override
Create a custom CSS class and apply it to specific component instances. This gives fine-grained control without affecting other instances.
```css theme={"theme":{"light":"one-light","dark":"night-owl"}}
.my-component-variant {
--bq---: value;
}
```
```html theme={"theme":{"light":"one-light","dark":"night-owl"}}
Content
```
***
## Example: customizing the Badge component
The [Badge](/components/badge) component exposes the following CSS custom properties (see [`bq-badge.variables.scss`](https://github.com/Endava/BEEQ/blob/main/packages/beeq/src/components/badge/scss/bq-badge.variables.scss)):
```css theme={"theme":{"light":"one-light","dark":"night-owl"}}
--bq-badge--background-color: /* Badge background */
--bq-badge--box-shadow: /* Badge shadow */
--bq-badge--border-color: /* Badge border color */
--bq-badge--border-radius: /* Badge border radius */
--bq-badge--border-style: /* Badge border style */
--bq-badge--border-width: /* Badge border width */
--bq-badge--size-small: /* Small badge size (8px) */
--bq-badge--size-medium: /* Medium badge size (12px) */
--bq-badge--size-large: /* Large badge size (16px) */
--bq-badge--text-color: /* Badge text color */
```
### Global override
Applies the custom styles to every `bq-badge` in the application.
:host {
flex-direction: row !important;
flex-wrap: wrap !important;
}
bq-badge {
--bq-badge--background-color: var(--bq-green-400);
--bq-badge--box-shadow: var(--bq-box-shadow--l);
--bq-badge--border-color: var(--bq-green-600);
--bq-badge--border-style: solid;
--bq-badge--border-width: 1px;
--bq-badge--border-radius: 4px;
}
99+
`}
>
```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
bq-badge {
--bq-badge--background-color: var(--bq-green-400);
--bq-badge--box-shadow: var(--bq-box-shadow--l);
--bq-badge--border-color: var(--bq-green-600);
--bq-badge--border-style: solid;
--bq-badge--border-width: 1px;
--bq-badge--border-radius: 4px;
}
```
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
99+
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqBadge } from "@beeq/react";
import "./styles.css";
// Import the CSS override in your global stylesheet
99+
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqBadge } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqBadge],
template: `
99+
`,
styles: [`
bq-badge {
--bq-badge--background-color: var(--bq-green-400);
--bq-badge--box-shadow: var(--bq-box-shadow--l);
--bq-badge--border-color: var(--bq-green-600);
--bq-badge--border-style: solid;
--bq-badge--border-width: 1px;
--bq-badge--border-radius: 4px;
}
`],
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
99+
```
### Targeted override
Only the `bq-badge` elements with the matching CSS class will have the overridden style.
:host {
flex-direction: row !important;
flex-wrap: wrap !important;
}
bq-badge.success {
--bq-badge--background-color: var(--bq-green-400);
--bq-badge--box-shadow: var(--bq-box-shadow--l);
--bq-badge--border-color: var(--bq-green-600);
--bq-badge--border-style: solid;
--bq-badge--border-width: 1px;
--bq-badge--border-radius: 4px;
}
99+completed
`}
>
```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
bq-badge.success {
--bq-badge--background-color: var(--bq-green-400);
--bq-badge--box-shadow: var(--bq-box-shadow--l);
--bq-badge--border-color: var(--bq-green-600);
--bq-badge--border-style: solid;
--bq-badge--border-width: 1px;
--bq-badge--border-radius: 4px;
}
```
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
99+completed
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqBadge } from "@beeq/react";
import "./styles.css";
// Import the CSS override in your global stylesheet
99+completed
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqBadge } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqBadge],
template: `
99+completed
`,
styles: [`
bq-badge.success {
--bq-badge--background-color: var(--bq-green-400);
--bq-badge--box-shadow: var(--bq-box-shadow--l);
--bq-badge--border-color: var(--bq-green-600);
--bq-badge--border-style: solid;
--bq-badge--border-width: 1px;
--bq-badge--border-radius: 4px;
}
`],
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
99+completed
```
***
## Best practices
Do
Prefer declarative color variables (`--bq-background--primary`) over primitive values (`--bq-grey-100`) in your custom themes for better consistency and automatic light/dark mode switching.
Don't
Do not hardcode raw hex values (e.g. `#ffffff`, `#1f2937`) in component overrides — they will not adapt to theme or mode changes automatically.
Do
Use CSS classes or component selectors to scope component overrides to specific instances and avoid unintended side effects elsewhere in the app.
Don't
Do not apply a global component override (e.g. `bq-badge { ... }`) unless you intentionally want it to affect every instance across the entire application.
Do
Always test your component overrides in both light and dark modes to verify proper contrast, readability, and visual consistency.
Don't
Do not skip contrast validation. WCAG 2.1 Level AA requires a 4.5:1 ratio for normal text and 3:1 for large text — overriding colors without checking can fail these requirements.
Do
Use the [primitive color palette](/foundations/colors#primitive-color-scales) as the source for custom theme colors. It includes blue, coral, cyan, gold, green, indigo, iris, lime, magenta, orange, purple, red, sky, teal, volcano, and yellow — each with 10 shades (100–1000).
Don't
Do not invent arbitrary color values outside the palette. Random hex colors break visual harmony and make future theme maintenance much harder.