#UIConfig

Applies to: all adapters.

UIConfig controls the visual shell of the dashboard: title, logo, favicon, locale, polling, misc links. Pass it via setUIConfig() on the server adapter, or forward it through createBullBoard({ options: { uiConfig } }).

#Usage

import { createBullBoard } from '@bull-board/api';
import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
import { ExpressAdapter } from '@bull-board/express';

const serverAdapter = new ExpressAdapter();
serverAdapter.setBasePath('/admin/queues');

createBullBoard({
  queues: [new BullMQAdapter(emailQueue)],
  serverAdapter,
  options: {
    uiConfig: {
      boardTitle: 'My Queues',
      boardLogo: {
        path: 'https://cdn.example.com/logo.png',
        width: '120px',
        height: 32,
      },
      miscLinks: [{ text: 'Logout', url: '/logout', icon: '/static/logout.svg' }],
      hideRedisDetails: true,
      showMetrics: true,
      hideDocsLink: false,
    },
  },
});

serverAdapter.setUIConfig({ ... }) directly works the same way, createBullBoard just forwards options.uiConfig to it.

#Fields

All fields are optional. Defaults are applied by createBullBoard where noted.

#Date formats

The three dateFormats entries are Intl.DateTimeFormatOptions objects, not format strings. The dashboard picks one by how far away the timestamp is, and passes it to Intl.DateTimeFormat along with the active language, so the output follows the viewer's locale.

uiConfig: {
  dateFormats: {
    short: { hour: '2-digit', minute: '2-digit' },
    common: { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' },
    full: { dateStyle: 'medium', timeStyle: 'short' },
  },
}

Leave one out and that case keeps its shipped default.

With showMetrics on, each queue view gains a throughput chart of completed and failed jobs per minute over the last hour.

The demo site uses this exact configuration, { label: 'demo', color: '#f59f00', textColor: '#000' }. See it live.

#Theming

For a worked walkthrough with screenshots, see Whitelabel the dashboard. What follows is the reference.

The dashboard is styled entirely from CSS custom properties, and theme lets you override them per colour scheme without forking the UI. Token names follow the shadcn theme contract, so palettes generated by shadcn-compatible theme editors drop straight in.

uiConfig: {
  theme: {
    light: {
      primary: '#6d28d9',
      radius: '0.75rem',
      'font-sans': "'Inter', system-ui, sans-serif",
    },
    dark: {
      primary: '#a78bfa',
    },
  },
}

That is a whole rebrand. primary is the one token the rest of the interactive palette hangs off: the focus ring, the sidebar's active entry and its ring all resolve to it, and hover and selection are mixed from it at 8%, 16% and 24%. Setting it moves every one of them together. The same holds elsewhere: foreground carries the text colour on cards and popovers, and the chart-1 to chart-5 ramp resolves to the job status colours the board plots, so recolouring status-completed recolours the completed series with it.

Each derived name is still individually overridable, and an override wins over the derivation. Set ring when you want a focus ring that is not your brand colour; leave it out when you don't.

Every key is optional, and anything you leave out keeps the shipped value. The available tokens are the core surface and interaction set (background, foreground, card, card-foreground, popover, popover-foreground, primary, primary-foreground, secondary, secondary-foreground, muted, muted-foreground, accent, accent-foreground, destructive, destructive-foreground, border, input, ring, radius), the typography tokens (font-sans, font-mono), the sidebar set (sidebar, sidebar-foreground, sidebar-primary, sidebar-primary-foreground, sidebar-accent, sidebar-accent-foreground, sidebar-border, sidebar-ring), the chart ramp (chart-1 through chart-5), and the job status colours (status-failed, status-completed, status-waiting, status-waiting-children, status-prioritized, status-active, status-delayed, status-paused).

The interaction states are tokens too: state-hover, state-selected, state-selected-hover and state-selected-foreground, plus their sidebar-state-* counterparts. They are mixed from primary and sidebar-primary, so set them only if you want a hovered or selected control to sit somewhere other than 8%, 16% and 24% of your brand colour.

Elevation is four more: shadow-popover is the one recipe every floating surface uses, from menus and toasts to both kinds of tooltip; shadow-control is the hairline the checkbox and the switch thumb carry in place; shadow-ring is the halo a focused input or checkbox draws, derived from ring so retinting the board moves it too; and overlay is what a modal puts between itself and the board. They take whatever box-shadow and background-color accept, so shadow-popover: 'none' gives you a flat board with borders only.

Values are plain CSS values. Unknown token names and values containing ;, {, }, < or > are dropped, so a theme can never inject arbitrary CSS or markup into the page.

#Source of truth

The authoritative type is in packages/api/typings/app.d.ts (UIConfig). Defaults live in packages/api/src/index.ts.