TaskbarMOL
The bar along a desktop's edge. It holds a Start Button, buttons of the page's own (launchers), one button per open window and a Tray. The window buttons are the Window Manager's model, rendered on every change: pressed for the window in front, a click brings a window to the front, minimizes the one in front or brings a minimized one back. Bound to a taskbar, the manager hides minimized windows - they live on their buttons. The bar sits on any edge and lines its buttons up from the start or in the middle; a .desktop wrapper lays the window area out beside it.
On this page (6)
§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:
| State | Type | Values | Default | Description |
|---|
§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.
| State | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
default | The bar - where it sits and how its buttons line up.
|
Every element
| Member | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
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.
Returns | |||||||||
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 | |||||||||
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.
Returns | |||||||||
el.api.settled(): Promise<void> | Wait for the last state's DOM work (async states: a diagram rendering, a chart mounting). Returns | |||||||||
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
| Member | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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.
Returns | ||||||||||||
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.
Returns | ||||||||||||
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.
Returns | ||||||||||||
df$.shadcn.taskbarApi.store(el: HTMLElement): Store<{ name: TaskbarState; config: TaskbarStateConfigs[TaskbarState] }> | The element's store (bindComponent made it).
Returns | ||||||||||||
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.
| ||||||||||||
df$.shadcn.taskbarStates: TaskbarState[] | The declared states, 'default' first: default. |
df$.shadcn.taskbar
| Member | Description | ||||||
|---|---|---|---|---|---|---|---|
manager(target: string | HTMLElement): HTMLElement | null | The Window Manager a taskbar shows.
Returns |
Types
| Type | Description |
|---|---|
TaskbarPosition | Where the bar sits. = |
§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