ToolbarX

A premium configurable toolbar with golden glow & 60+ icons

Selected
Dashboard
Manage your overview panels and widgets

Built-in Icons (60+)

Introduction

ToolbarX

A premium, configurable toolbar/menu UI component library. Zero dependencies — pure vanilla JS & CSS, under 20 KB total. Drop it into any web app and get an animated, themeable navigation bar in minutes.

  • Dark & Light themes with animated golden glow sliding pill
  • Horizontal & vertical orientation, switchable at runtime
  • Fully configurable dimensions — item size, icon size, padding, radii, and glow spread
  • 60+ built-in SVG icons across 10 categories, all using currentColor
  • Custom icon support — inline SVG string, function-based (dynamic sizing), or global registry
  • Responsive auto-scaling via ResizeObserver (0.6×–1.0× CSS transform)
  • Spring-eased pill animation using cubic-bezier(0.34, 1.56, 0.64, 1)
  • Zero runtime dependencies, < 20 KB total (JS + CSS)
Getting Started

Quick Start

1
Install & include
via npm
npm install toolbar-x
then reference from node_modules
<link rel="stylesheet" href="node_modules/toolbar-x/src/toolbar.css">
<script src="node_modules/toolbar-x/src/icons.js"></script>
<script src="node_modules/toolbar-x/src/toolbar.js"></script>
or via CDN (no install needed)
<link rel="stylesheet" href="https://unpkg.com/toolbar-x/src/toolbar.css">
<script src="https://unpkg.com/toolbar-x/src/icons.js"></script>
<script src="https://unpkg.com/toolbar-x/src/toolbar.js"></script>
2
Add a container element
<div id="toolbar-container"></div>
3
Initialize
const toolbar = new ToolbarX({
  container: '#toolbar-container',
  theme: 'dark',
  items: [
    { id: 'home', icon: 'home', label: 'Home' },
    { id: 'analytics', icon: 'chart', label: 'Analytics' },
    { id: 'layers', icon: 'layers', label: 'Layers' },
    { id: 'settings', icon: 'settings', label: 'Settings' },
  ],
  onSelect: (item) => console.log('Selected:', item.id),
});
Configuration

Constructor Options

All options are passed as a single object to new ToolbarX(options). Only container is required.

Option Type Default Description
container required string | Element — CSS selector or DOM element to render into
theme string 'dark' 'dark' or 'light'
orientation string 'horizontal' 'horizontal' or 'vertical'
items Array [] Array of { id, icon, label } objects
activeItem string first item ID of the initially active item
showThemeToggle boolean true Show the built-in theme toggle button
responsive boolean true Auto-scale via ResizeObserver when container is narrow
customIcons object {} Map of custom icons { name: svgString }
onSelect function null Called on item click: (item) => {}
onThemeChange function null Called when theme changes: (theme) => {}
onOrientationChange function null Called when orientation changes: (orientation) => {}

Dimension Options

Dimension options can be set in the constructor alongside other options, or updated live via setDimensions(). All values are in pixels.

Option Default Description
itemSize 72 Item cell width and height (px)
iconSize 30 SVG icon render size (px)
outerPadding 10 Outer container padding (px)
innerPadding 6 Inner track padding (px)
outerRadius 28 Outer container border radius (px)
innerRadius 20 Inner track border radius (px)
itemRadius 18 Item button and pill border radius (px)
glowSpread 5 Golden glow spread radius around the active pill (px)
sectionGap 10 Gap between the item track and the theme toggle (px)

Size Presets

Small
toolbar.setDimensions({
  itemSize: 48, iconSize: 20,
  outerPadding: 7, innerPadding: 4,
  outerRadius: 20, innerRadius: 14, itemRadius: 12,
  glowSpread: 3, sectionGap: 7,
});
Medium
toolbar.setDimensions({
  itemSize: 60, iconSize: 26,
  outerPadding: 8, innerPadding: 5,
  outerRadius: 24, innerRadius: 17, itemRadius: 15,
  glowSpread: 4, sectionGap: 8,
});
Large (default)
toolbar.setDimensions({
  itemSize: 72, iconSize: 30,
  outerPadding: 10, innerPadding: 6,
  outerRadius: 28, innerRadius: 20, itemRadius: 18,
  glowSpread: 5, sectionGap: 10,
});
X-Large
toolbar.setDimensions({
  itemSize: 88, iconSize: 36,
  outerPadding: 12, innerPadding: 8,
  outerRadius: 32, innerRadius: 24, itemRadius: 22,
  glowSpread: 6, sectionGap: 12,
});
API Reference

Public Methods

All methods are called on the ToolbarX instance returned by the constructor.

Method Description
setActive(id) Animate the pill to the item with the given ID
setTheme('dark' | 'light') Switch to the specified theme
toggleTheme() Toggle between dark and light themes
setOrientation('horizontal' | 'vertical') Change the toolbar layout orientation
setDimensions({ ... }) Update one or more dimension values live; accepts any subset of dimension options
registerIcon(name, svg) Register a custom icon on this instance (string or function)
getAvailableIcons() Returns an array of all icon names available to this instance (built-in + custom)
getTheme() Returns the current theme string ('dark' or 'light')
getActiveItem() Returns the currently active item ID
getOrientation() Returns the current orientation string
destroy() Remove the toolbar from the DOM and disconnect all observers/listeners
Icons

Built-in Icons

60+ SVG icons are included across 10 categories. All icons use currentColor, so they automatically adapt to the active theme. Use any icon name as the icon field on a toolbar item.

Category Icon names
Navigation home grid menu compass map arrow-left arrow-right
Search search filter
User & Social user users user-plus heart thumbs-up share
Communication bell mail message-circle phone send
Commerce wallet credit-card shopping-cart shopping-bag tag dollar-sign gift
Data chart bar-chart pie-chart trending-up activity layers
Files folder file clipboard download upload image
Media play pause music camera video mic
Dev & Tools settings sliders terminal code database cloud lock unlock key
Misc star bookmark flag alert-circle check-circle clock calendar globe link external-link trash edit plus minus x refresh eye print

Custom Icons

There are three ways to bring your own icons.

Option 1 — Via constructor
const toolbar = new ToolbarX({
  customIcons: {
    'my-icon': '<svg width="24" height="24" viewBox="0 0 24 24">...</svg>',
  },
  items: [{ id: 'custom', icon: 'my-icon', label: 'Custom' }],
});
Option 2 — Register at runtime
// Instance level — only this toolbar
toolbar.registerIcon('rocket', '<svg>...</svg>');

// Global level — available to all ToolbarX instances
ToolbarXIcons.register('rocket', '<svg>...</svg>');
Option 3 — Function-based (dynamic sizing)
ToolbarXIcons.register('diamond', (size) =>
  `<svg width="${size}" height="${size}" viewBox="0 0 24 24"
    fill="none" stroke="currentColor" stroke-width="1.8">
    <polygon points="12 2 22 12 12 22 2 12"/>
  </svg>`
);
List available icons
toolbar.getAvailableIcons();
// → ['home', 'grid', 'menu', 'compass', ...]

ToolbarXIcons.list();
// → ['home', 'grid', 'menu', 'compass', ...]
Events

Callbacks

ToolbarX uses constructor callbacks rather than DOM events. All three callbacks receive a single argument.

const toolbar = new ToolbarX({
  // ...
  onSelect: (item) => {
    // item = { id, icon, label }
    console.log('Selected:', item.id, item.label);
  },
  onThemeChange: (theme) => {
    // theme = 'dark' | 'light'
    document.body.className = theme;
  },
  onOrientationChange: (orientation) => {
    // orientation = 'horizontal' | 'vertical'
    console.log('Orientation:', orientation);
  },
});
Layout

Vertical Orientation

Use vertical orientation for sidebar-style navigation. The pill animation, glow, and responsive scaling all work identically in vertical mode.

// Set on construction
const toolbar = new ToolbarX({
  container: '#sidebar',
  orientation: 'vertical',
  // ...
});

// Or switch at runtime
toolbar.setOrientation('vertical');
toolbar.setOrientation('horizontal');