Theme
Design your own
On this page (6)
Component Skill — components/taskbar/component-skill.md

Native basis

A <nav> of buttons. data-taskbar-for names the Window Manager; the runtime renders button.taskbar-windows into .taskbar-windows from its window-manager-change event. Everything else is authored.

Web Platform APIs

CustomEventaria-pressed:has()backdrop-filter

Variants

• data-position="top|left|right" - the edge (default bottom); left and right make a column with icon-only window buttons.

• data-align="center" - Start, launchers and windows centred; the Tray stays at the end.

§A desktop

Window Manager, Desktop Manager, Taskbar, Start Button, Start Menu and Tray together. Double-click an icon or pick an app from Start: its window opens and gets a button. Click a button to bring its window forward, again to minimize it. The strip at the far right shows the desktop.

§Edges and centring

The same bar on the left edge (a column of icon buttons) and centred at the bottom - the Start Button moves with the window buttons, the Tray stays at the end.

§States

Named states via the shared State API, bound on each .taskbar:

  • default - the bar; { position, align } move it to an edge and line its buttons up

The first example carries data-state-demo; bun run screenshots drives it via el.api.setState(name) and captures screenshots/{mode}/taskbar-{state}.png.

Machine contract - verified against taskbar.schema.json by bun run verify:

StateTypeValuesDefaultDescription

§API

Generated from taskbar.ts and the shared State API - the descriptions are their JSDoc, the types are checked by the compiler.

States

type TaskbarState = 'default' - setState(name, config) takes the config of the state it names.

StateDescription
default
The bar - where it sits and how its buttons line up.
Config fieldTypeDescription
position?TaskbarPositionthe edge it sits on (data-position, default bottom)
align?'start' | 'center'the window buttons from the start, or centred with the Start Button (data-align, default start)

Every element

MemberDescription
el.api.setState<S extends TaskbarState>(name: S, config?: TaskbarStateConfigs[S]): unknown
Enter a state: the DOM work runs (also when it is the current state), the store records it.
ArgumentTypeDescription
nameSa declared state (an unknown name throws)
config?TaskbarStateConfigs[S]that state's config (merged into the stored one when the component merges)

Returns unknown - what the state's DOM work returned - a Promise for an async state (or await settled())

el.api.getState(): { name: TaskbarState; config: TaskbarStateConfigs[TaskbarState]; model?: ElementModel }
The state the element shows now - read back from the DOM, so it includes what the user changed.

Returns { name: TaskbarState; config: TaskbarStateConfigs[TaskbarState]; model?: ElementModel } - the state's name, its config and the authored markup model render() starts from

el.api.render(state?: { name: TaskbarState; config: TaskbarStateConfigs[TaskbarState]; model?: ElementModel }): string
The element's markup in a state - the authored markup with that state applied; a pure function of the state.
ArgumentTypeDescription
state?{ name: TaskbarState; config: TaskbarStateConfigs[TaskbarState]; model?: ElementModel }a state as getState() returns it (default: the current one)

Returns string - the element's outer HTML in that state

el.api.settled(): Promise<void>
Wait for the last state's DOM work (async states: a diagram rendering, a chart mounting).

Returns Promise<void> - resolves when nothing is pending

el.store: Store<{ name: TaskbarState; config: TaskbarStateConfigs[TaskbarState] }>A defuss-store store of the element's state - subscribe to follow every change (also the user's), set it to drive the component.

Registry

MemberDescription
df$.shadcn.taskbarApi.setState<S extends TaskbarState>(el: HTMLElement, name: S, config?: TaskbarStateConfigs[S]): unknown
Enter a state: the DOM work runs (also when it is the current state), the store records it.
ArgumentTypeDescription
elHTMLElementthe component's element
nameSa declared state (an unknown name throws)
config?TaskbarStateConfigs[S]that state's config (merged into the stored one when the component merges)

Returns unknown - what the state's DOM work returned - a Promise for an async state (await it, or el.api.settled())

df$.shadcn.taskbarApi.getState(el: HTMLElement): { name: TaskbarState; config: TaskbarStateConfigs[TaskbarState]; model?: ElementModel }
The state the element shows now - read back from the DOM, so it includes what the user changed.
ArgumentTypeDescription
elHTMLElementthe component's element

Returns { name: TaskbarState; config: TaskbarStateConfigs[TaskbarState]; model?: ElementModel } - the state's name, its config and the authored markup model render() starts from

df$.shadcn.taskbarApi.render(state: { name: TaskbarState; config: TaskbarStateConfigs[TaskbarState]; model?: ElementModel }): string
The element's markup in a state - the authored markup with that state applied; a pure function of the state.
ArgumentTypeDescription
state{ name: TaskbarState; config: TaskbarStateConfigs[TaskbarState]; model?: ElementModel }a state as getState() returns it (with its model)

Returns string - the element's outer HTML in that state

df$.shadcn.taskbarApi.store(el: HTMLElement): Store<{ name: TaskbarState; config: TaskbarStateConfigs[TaskbarState] }>
The element's store (bindComponent made it).
ArgumentTypeDescription
elHTMLElementthe component's element

Returns Store<{ name: TaskbarState; config: TaskbarStateConfigs[TaskbarState] }> - a defuss-store store of { name, config } - subscribe to follow every change, set it to drive the component

df$.shadcn.taskbarApi.commit<S extends TaskbarState>(el: HTMLElement, name: S, config?: TaskbarStateConfigs[S]): void
Record a state the element reached on its own (no DOM work) - for a component's own handlers.
ArgumentTypeDescription
elHTMLElementthe component's element
nameSthe state it is in
config?TaskbarStateConfigs[S]its config
df$.shadcn.taskbarStates: TaskbarState[]The declared states, 'default' first: default.

df$.shadcn.taskbar

MemberDescription
manager(target: string | HTMLElement): HTMLElement | null
The Window Manager a taskbar shows.
ArgumentTypeDescription
targetstring | HTMLElementthe .taskbar element, its id or a selector

Returns HTMLElement | null - its .window-manager, null when it names none

Types

TypeDescription
TaskbarPosition
Where the bar sits.

= 'bottom' | 'top' | 'left' | 'right'

§CSS view file

/* -- Taskbar component --------------------------------------------
   The bar along a desktop's edge: the Start Button, launchers, one button per
   open window (rendered from the Window Manager) and the Tray at the end.
   data-position puts it on any edge (left / right: a column), data-align
   centres the buttons with the Start Button (the Tray stays at the end). */
@layer components {
  .taskbar {
    --taskbar-size: 3rem;
    position: relative;
    z-index: 40;
    box-sizing: border-box;
    display: flex;
    align-items: center;
    gap: 0.25rem;
    min-height: var(--taskbar-size);
    padding: 0.25rem 0.375rem;
    border-block-start: 1px solid var(--border);
    background: color-mix(in oklch, var(--card) 88%, transparent);
    color: var(--card-foreground);
    font-family: var(--font-sans);
    font-size: 0.8125rem;
    backdrop-filter: blur(16px);
    &[data-position="top"] {
      border-block-start: 0;
      border-block-end: 1px solid var(--border);
    }
    &:is([data-position="left"], [data-position="right"]) {
      flex-direction: column;
      min-height: 0;
      min-width: var(--taskbar-size);
      padding: 0.375rem 0.25rem;
      border-block-start: 0;
      border-inline-end: 1px solid var(--border);
    }
    &[data-position="right"] {
      border-inline-end: 0;
      border-inline-start: 1px solid var(--border);
    }
  }
  .taskbar-launchers,
  .taskbar-windows {
    display: flex;
    align-items: center;
    gap: 0.125rem;
    min-width: 0;
    .taskbar:is([data-position="left"], [data-position="right"]) & {
      flex-direction: column;
    }
  }
  .taskbar-windows {
    flex: 1;
    overflow: hidden;
  }
  /* centred: Start, launchers and windows together in the middle */
  .taskbar[data-align="center"] {
    & > :first-child {
      margin-inline-start: auto;
    }
    & .taskbar-windows {
      flex: 0 1 auto;
      margin-inline-end: auto;
    }
  }
  .taskbar-launcher,
  .taskbar-window {
    position: relative;
    display: inline-flex;
    align-items: center;
    gap: 0.5rem;
    height: 2.5rem;
    min-width: 2.5rem;
    max-width: 11rem;
    padding-inline: 0.5rem;
    border: 0;
    border-radius: var(--radius-md);
    background: none;
    color: inherit;
    font: inherit;
    cursor: default;
    &:hover {
      background: color-mix(in oklch, var(--accent) 70%, transparent);
    }
    &:focus-visible {
      outline: 2px solid var(--ring);
      outline-offset: -2px;
    }
    & svg,
    & img,
    & .desktop-glyph {
      width: 1.25rem;
      height: 1.25rem;
      flex: none;
    }
  }
  .taskbar-window {
    flex: 0 1 11rem;
    justify-content: flex-start;
    /* the line under a window's button: thin when open, long when in front */
    &::after {
      content: "";
      position: absolute;
      inset-block-end: 0.125rem;
      inset-inline: 40%;
      height: 3px;
      border-radius: 2px;
      background: var(--muted-foreground);
    }
    &[aria-pressed="true"] {
      background: var(--accent);
      color: var(--accent-foreground);
      &::after {
        inset-inline: 25%;
        background: var(--primary);
      }
    }
    &[data-minimized] {
      opacity: 0.8;
    }
  }
  .taskbar-window-icon {
    display: contents;
  }
  .taskbar-window-title {
    min-width: 0;
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
    .taskbar:is([data-position="left"], [data-position="right"]) & {
      display: none;
    }
  }
  @media (prefers-reduced-motion: reduce) {
    .taskbar {
      backdrop-filter: none;
    }
  }
  @media (forced-colors: active) {
    .taskbar-window[aria-pressed="true"] {
      outline: 2px solid Highlight;
    }
  }
}

§JavaScript view file

The window buttons are rendered from the Window Manager's window-manager-change; a click is df$.shadcn.windowManager.toggle().

// -- Taskbar ------------------------------------------------------
// The bar along a desktop's edge: a Start Button, buttons of the page's own
// (launchers), one button per open window of the Window Manager it names
// (data-taskbar-for) and a Tray. The window buttons are the manager's model,
// rendered on every window-manager-change: pressed = the window in front, a
// click brings a window to the front or minimizes the one in front
// (df$.shadcn.windowManager.toggle). With a taskbar bound, the manager hides
// minimized windows - they live on their buttons.
// VERIFIED: (taskbar.e2e) a click on the front window's button minimizes it, on any other brings it to the front
// - the button asks the Window Manager (toggle), so the bar and the manager never disagree.
// Shared preamble (AGENTS.md "State API"); the implementation lives in core.js —
// build.ts rewrites this import into a df$.shadcn.shared binding in dist/.
import { defussGlobals, defussQuery, componentState, bindComponent } from '../../../shared/state-api.js';
const df$ = defussGlobals();
const dfDollar = defussQuery();
/** An element by id, through df$ (null when none has it). */
const byId = (id: string | null | undefined): HTMLElement | null =>
  (id ? (dfDollar('#' + CSS.escape(id)).get(0) as HTMLElement | undefined) : undefined) ?? null;
/** Where the bar sits. */
type TaskbarPosition = 'bottom' | 'top' | 'left' | 'right';
const taskbarStates = ['default'];
/** setState() configs per state. */
export interface TaskbarStateConfigs {
  /** The bar - where it sits and how its buttons line up. */
  default: {
    /** the edge it sits on (data-position, default bottom) */
    position?: TaskbarPosition;
    /** the window buttons from the start, or centred with the Start Button (data-align, default start) */
    align?: 'start' | 'center';
  };
}
const POSITIONS = ['bottom', 'top', 'left', 'right'];
const managerOf = (bar: HTMLElement): HTMLElement | null => {
  const id = bar.dataset.taskbarFor;
  return id ? byId(id) : null;
};
/** The markup of a state: its position and alignment as data attributes. */
function applyMarkup(bar, _stateName, config) {
  if (config.position !== undefined)
    dfDollar(bar).attr('data-position', config.position === 'bottom' ? null : config.position);
  if (config.align !== undefined) dfDollar(bar).attr('data-align', config.align === 'start' ? null : config.align);
}
/** The one function that changes the bar for a state: its edge and its alignment. */
function triggerStateChange(bar, stateName, config) {
  if (config.position !== undefined && !POSITIONS.includes(config.position))
    throw new Error(`taskbar: no position ${config.position}`);
  applyMarkup(bar, stateName, config);
}
/** Registry-level API; pass the .taskbar element explicitly. Unknown names throw. */
export const taskbarApi = componentState({
  component: 'taskbar',
  states: taskbarStates,
  apply: (bar, state) => triggerStateChange(bar, state.name, state.config),
  read: (bar) => ({
    name: 'default',
    config: { position: bar.dataset.position || 'bottom', align: bar.dataset.align || 'start' },
  }),
  markup: (el, state) => applyMarkup(el, state.name, state.config),
});
df$.taskbarApi = taskbarApi;
df$.taskbarStates = taskbarStates;
/** One button per window: its icon, its title, pressed while it is in front. */
function render(bar: HTMLElement, windows) {
  const list = dfDollar(bar).find('.taskbar-windows').get(0) as HTMLElement | undefined;
  if (!list) return;
  const have = new Map(
    dfDollar(list)
      .find<HTMLButtonElement>(':scope > .taskbar-window')
      .toArray()
      .map((b) => [b.dataset.window, b]),
  );
  const keep = new Set<string>();
  for (const w of windows) {
    keep.add(w.id);
    let b = have.get(w.id);
    if (!b) {
      b = document.createElement('button');
      b.type = 'button';
      b.className = 'taskbar-window';
      b.dataset.window = w.id;
      dfDollar(b).html(
        '<span class="taskbar-window-icon" aria-hidden="true"></span><span class="taskbar-window-title"></span>',
      );
    }
    list.append(b); // in the manager's order
    const icon = dfDollar(b).find('.taskbar-window-icon').get(0) as HTMLElement;
    // a Desktop glyph (it follows the look) or a Lucide icon
    const key = w.glyph ? `glyph:${w.glyph}` : w.icon;
    if (icon.dataset.icon !== key) {
      icon.dataset.icon = key;
      dfDollar(icon).html(
        w.glyph
          ? `<span class="desktop-glyph" data-glyph="${w.glyph}"></span>`
          : w.icon
            ? `<i data-lucide="${w.icon}"></i>`
            : '',
      );
    }
    const title = dfDollar(b).find('.taskbar-window-title').get(0) as HTMLElement;
    if (title.textContent !== w.title) title.textContent = w.title;
    b.title = w.title;
    b.setAttribute('aria-pressed', String(w.active && w.state !== 'minimized'));
    b.toggleAttribute('data-minimized', w.state === 'minimized');
  }
  for (const [id, b] of have) if (!keep.has(id)) b.remove();
  if (windows.some((w) => w.icon)) globalThis.lucide?.createIcons?.();
}
function bind(bar: HTMLElement) {
  const m = managerOf(bar);
  if (m) {
    m.setAttribute('data-taskbar', '');
    m.addEventListener('window-manager-change', (e) => render(bar, (e as CustomEvent).detail.windows));
    const model = df$.windowManager?.windows(m);
    if (model) render(bar, model);
  }
  bar.addEventListener('click', (e) => {
    const b = (e.target as Element).closest('.taskbar-window') as HTMLElement | null;
    if (b?.dataset.window) df$.windowManager?.toggle(b.dataset.window);
  });
  // arrows move between the bar's buttons (one tab stop for the window list)
  bar.addEventListener('keydown', (e) => {
    const list = (e.target as Element).closest('.taskbar-windows');
    if (!list || !['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End'].includes(e.key)) return;
    const all = dfDollar(list).find<HTMLElement>('.taskbar-window').toArray();
    const at = all.indexOf(e.target as HTMLElement);
    const next =
      e.key === 'Home'
        ? all[0]
        : e.key === 'End'
          ? all.at(-1)
          : all[(at + (e.key === 'ArrowRight' || e.key === 'ArrowDown' ? 1 : -1) + all.length) % all.length];
    if (next) {
      e.preventDefault();
      next.focus();
    }
  });
}
/**
 * The Window Manager a taskbar shows.
 * @param target - the .taskbar element, its id or a selector
 * @returns its .window-manager, null when it names none
 */
const manager = (target: string | HTMLElement): HTMLElement | null => {
  const bar =
    typeof target === 'string'
      ? (byId(target) ?? (dfDollar(target).get(0) as HTMLElement | undefined) ?? null)
      : target;
  return bar ? managerOf(bar) : null;
};
/** df$.shadcn.taskbar - the bar's link to its desktop. */
export const taskbarActions = { manager };
df$.taskbar = taskbarActions;
function init() {
  dfDollar('.taskbar:not([data-init])')
    .toArray()
    .forEach((bar) => {
      bar.dataset.init = '';
      bind(bar);
      // el.store + el.api (AGENTS.md "State through stores")
      bindComponent(bar, taskbarApi);
    });
}
init();
new MutationObserver(init).observe(document, { childList: true, subtree: true });

Comments, ideas or improvements? Edit this page's source on GitHub