TitleBar

A window title bar (app shell chrome): drag region + centered title / document well + built-in window actions + compact/large sizes. Semantics live at the "window" level, serving Electron/Tauri hosts; in plain Web the drag attributes are harmless no-ops and the component degrades to app shell semantics (distinct from oas-app-bar, the page-level role="banner").

Basic usage

title / subtitle set the centered title and subtitle (document state etc.); window-actions declares built-in window action buttons as a comma-separated subset (minimize,maximize,close); clicking dispatches oas-window-action (the component only emits the event — the host wires Electron/Tauri APIs).

Title, subtitle and window actions

Click the window action buttons on the right and watch the event feedback (the component does not perform window operations).

Example

Drag contract (drag)

The drag boolean attribute turns the whole bar into a window drag region (writes -webkit-app-region: drag + data-tauri-drag-region, effective in Electron/Tauri hosts); interactive children automatically opt out (no-drag) — a curated set of native interactive elements and built-in interactive components (button / input / segmented / toolbar / scope-bar / knob etc.) plus [data-no-drag]-marked elements remain clickable; host oas-* children outside the curated list should be marked [data-no-drag] by the host. In plain Web this is a harmless no-op.

Buttons inside the drag region stay clickable (automatic no-drag)

Click meAction

Example

Document well (editable)

The editable boolean attribute turns the title into an editable input (Enter or blur commits, Esc cancels and rolls back); committing dispatches oas-title-change, and the title is absorbed into the component cache (title is a native global attribute — once rendered into the title area it is removed from the host, preventing duplicate native tooltips); hosts sync via the event. Rewriting title externally while editing terminates the edit (external state wins).

Editable document title

Edit the title and press Enter; watch oas-title-change and the title attribute write-back.

Example

Sizes (size)

size="compact" (default, 34px) / size="large" (68px); controls stay compact in large (only the bar height doubles).

compact / large comparison

Example

Safe area (native window control clearance)

Native window controls of hosts such as the Windows window controls overlay (WCO) may occupy both ends of the bar: yield the segments with the leading-inset / trailing-inset attributes (equivalent to overriding the --oas-titlebar-leading-inset / --oas-titlebar-trailing-inset variables, default space-2 (8px) on each side, so content never touches the edges). In WCO scenarios consume the env(titlebar-area-*) environment variables directly (falls back to space-2 outside WCO, no effect):

oas-titlebar {
  --oas-titlebar-leading-inset: env(titlebar-area-x, 0px);
  --oas-titlebar-trailing-inset: calc(100% - env(titlebar-area-width, 100%) - env(titlebar-area-x, 0px));
}

Slots

slot="leading" (brand / traffic lights), slot="center" (interactive content, overrides title / document well), slot="title" (rich title), slot="trailing" (end-of-bar content beyond window actions).

Slot composition

OAS Studio

scene-04.oasSynced

Example

RTL

With dir="rtl" on the container the component mirrors automatically: data-rtl hook + logical-properties-only layout.

RTL mirror

Example

macOS traffic lights

Place the built-in oas-traffic-lights (close / minimize / maximize dots, symbols on hover) in slot="leading" with a centered title for the macOS layout; clicks dispatch oas-window-action (same contract as the built-in window-actions).

macOS traffic lights + centered title

Click a traffic light to see the oas-window-action feedback

Example

API

oas-titlebar

Attributes

Attribute	Description	Type	Default
drag	Turns the whole bar into a window drag region (writes -webkit-app-region: drag + data-tauri-drag-region, effective in Electron/Tauri hosts; harmless no-op in plain Web); a curated set of interactive children automatically opts out (no-drag) — otherwise opt out a host child with [data-no-drag]	boolean	—
editable	Makes the document-well title editable: Enter or blur commits (dispatches oas-title-change and updates the absorbed cache), Esc cancels and rolls back; rewriting title externally while editing terminates the edit	boolean	—
leading-inset	Safe area: leading-side native-control clearance (CSS length; also settable via --oas-titlebar-leading-inset)	—	—
size	Height tier: compact (default, 34px) / large (68px, controls stay compact); invalid values fall back to compact with a one-time warning	string	compact
subtitle	Subtitle / document state (last edited time etc.)	string	—
title	Centered title text (overridden when slot="title" has content). Same-named as the native global attribute — absorbed (removed from the host) once rendered into the title area, preventing duplicate native tooltips; rendering is driven by the component-internal cache; to clear or reset, write the title attribute explicitly	string	—
trailing-inset	Safe area: trailing-side native-control clearance (CSS length; also settable via --oas-titlebar-trailing-inset)	—	—
window-actions	Built-in window action button subset (comma-separated: minimize,maximize,close); clicking dispatches oas-window-action — the component does not perform window operations	string	—

Events

Event	Description
oas-title-change	Dispatched when the document well commits (Enter/blur) with a changed value; detail { title }; the absorbed cache is updated (the title attribute does not stay on the host)
oas-window-action	Dispatched when a built-in window action button is clicked; detail { action } (minimize/maximize/close); the component only emits — hosts wire Electron/Tauri APIs

Slots

Name	Description
center	Central interactive content channel (overrides the title / document well when present, e.g. document tag combos)
leading	Custom area before the title (brand / macOS traffic lights provided by the host)
title	Rich title channel (overrides the title attribute text)
trailing	End-of-bar custom area (beyond the window action buttons)

CSS Variables

CSS Variable	Default
--oas-titlebar-bg	color-mix(in srgb, var(--oas-color-text-primary) 5%, var(--oas-color-bg))
--oas-titlebar-height	var(--oas-titlebar-compact-height, 34px)
--oas-titlebar-leading-inset	var(--oas-space-2)
--oas-titlebar-trailing-inset	var(--oas-space-2)

oas-traffic-lights

Attributes

Attribute	Description	Type	Default
disabled	Disables all three dots (native disabled + reduced opacity)	boolean	—

Events

Event	Description
oas-window-action	Fired on traffic-light click; detail { action } (minimize/maximize/close); the component only emits — the host wires Electron/Tauri APIs

CSS Variables

CSS Variable	Default
--oas-traffic-lights-close	#ff5f57
--oas-traffic-lights-gap	8px
--oas-traffic-lights-maximize	#28c840
--oas-traffic-lights-minimize	#febc2e
--oas-traffic-lights-size	12px
--oas-traffic-lights-symbol	rgba(0, 0, 0, 0.55)