Custom Color Schemes

Create branded Boreal UI palettes, register them with ThemeProvider, set a preferred starting scheme, or configure your app to use only your custom themes.

Example paletteCyberpunk Pulse

primaryColor#792348ff

secondaryColor#8338ec

tertiaryColor#3a0ca3

quaternaryColor#fb5607

backgroundColor#000000ff

Add custom schemes

Pass one or more custom palettes into ThemeProvider with the customSchemes prop.

Choose an initial scheme

Use initialSchemeName to make a custom scheme the first active theme.

Use custom schemes only

Enable useOnlyCustomSchemes when you want to exclude Boreal UI’s built-in schemes.

Create a custom color scheme

A custom scheme is a named object that follows Boreal UI’sColorScheme shape. Each value should be a valid CSS color string, usually a hex value.

customSchemes.ts

import type { ColorScheme } from "@boreal-ui/types";

export const customSchemes: ColorScheme[] = [
  {
    name: "Cyberpunk Pulse",
    primaryColor: "#792348ff",
    secondaryColor: "#8338ec",
    tertiaryColor: "#3a0ca3",
    quaternaryColor: "#fb5607",
    backgroundColor: "#000000ff",
  },
  {
    name: "Forest Dusk",
    primaryColor: "#7BAE7F",
    secondaryColor: "#4F6F52",
    tertiaryColor: "#D6CDA4",
    quaternaryColor: "#A27B5C",
    backgroundColor: "#1F2A24",
  },
];

Custom scheme properties

These are the core fields used by Boreal UI when creating theme variables from a color scheme.

namestring

The display name and lookup name for the color scheme.

primaryColorstring

The main brand/action color used across interactive UI.

secondaryColorstring

A supporting color for secondary actions and accents.

tertiaryColorstring

An additional accent color for expanded theme variation.

quaternaryColorstring

A fourth accent color for rich theme systems.

backgroundColorstring

The base application background color.

Register custom schemes with ThemeProvider

Pass your custom schemes into the customSchemes prop. By default, Boreal UI will make your custom schemes available alongside the built-in schemes.

AppThemeProvider.tsx

"use client";

import { ThemeProvider } from "@boreal-ui/next/ThemeProvider";
import { customSchemes } from "./customSchemes";

export function AppThemeProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <ThemeProvider customSchemes={customSchemes}>
      {children}
    </ThemeProvider>
  );
}

Set a custom scheme as the starting theme

Use initialSchemeName when you want a specific custom scheme to be selected when the app first loads.

initialSchemeName

<ThemeProvider
  customSchemes={customSchemes}
  initialSchemeName="Cyberpunk Pulse"
>
  {children}
</ThemeProvider>

How the initial scheme is resolved

If initialSchemeName is provided, Boreal UI can use it as the preferred starting scheme. If the user has already selected a scheme and that value is persisted, the saved value may be restored first depending on your provider setup.

Use only your custom schemes

Enable useOnlyCustomSchemes when your app should only expose the palettes you provide. This is useful for white-label apps, client projects, and tightly controlled design systems.

useOnlyCustomSchemes

<ThemeProvider
  customSchemes={customSchemes}
  initialSchemeName="Cyberpunk Pulse"
  useOnlyCustomSchemes
>
  {children}
</ThemeProvider>

When to use this

Use custom-only mode when you want to prevent users from selecting Boreal UI’s default themes. Your theme switcher will only receive the schemes from your customSchemes array.

Keep schemes in a dedicated file

For larger projects, keep custom palettes outside the provider file. This makes schemes easier to test, reuse, and update.

Recommended structure

src/
  app/
    AppThemeProvider.tsx
  theme/
    customSchemes.ts
    themeConfig.ts

Use unique names

Each custom scheme should have a unique name. The name is used for lookups, initial selection, and theme switcher labels.

Test contrast

Before shipping a custom palette, test text, buttons, cards, focus rings, disabled states, and table rows across light and dark surfaces.

Use valid CSS colors

Hex, RGB, HSL, and named CSS colors can work, but hex values are usually easiest to document and compare across a design system.