# bref-ui ## button An action or navigation control with text or icon labels, theme colors, five sizes, three variants, and wide, rounded or disabled options. ```svelte undefined} /> undefined} aria-label="Favorite" /> ``` Use href for navigation and onClick for actions. Other native button/anchor attributes and events are forwarded, except onclick and children. Give icon-only buttons an accessible name using aria-label or icon.label. Disabled links cannot navigate. Customize appearance with size, variant, color, glass, wide (text buttons) and rounded (icon buttons), or scoped native CSS. Props: href: string = Omitted — Render an anchor for navigation; omit for a native button.; label: string = Omitted — Visible text; omit for icon-only buttons.; icon: Omit = Omitted — Leading icon; required when label is omitted.; size?: Size = medium — x-small, small, medium, large or x-large.; variant?: Variant = neutral — neutral, soft or filled.; color?: Exclude = foreground — Theme color excluding background.; trailingIcon?: Omit = Omitted — Icon after the label; text buttons only.; wide?: boolean = false — Full width; text buttons only.; rounded?: boolean = false — Circular shape; icon-only buttons only.; glass?: boolean = false — Adds translucent paint and backdrop blur to the selected variant.; disabled?: boolean = false — Disables actions and navigation; uses muted paint for the selected variant.; onClick?: MouseEvent handler = Omitted — Click handler for actions and links; replaces native onclick. ## combobox Search local option labels while selected IDs stay separate from the query. ```svelte ``` Selected IDs remain separate from the editable search query. Bind a string for single selection or an array for multiple selection. Label with aria-label or aria-labelledby. Arrow keys move through results, Enter selects, Escape closes and restores selection. Native attributes are limited to the documented ComboboxNativeProps subset; name/form/required participate in forms and reset. Customize size, variant, wide, placeholder and emptyMessage. Props: items: readonly SelectOptionDataProps[] = — — Unique IDs, labels, optional icons and disabled state.; value?: string | string[] = undefined (bindable) — Bindable selected ID or IDs; an array enables multiple selection.; onChange?: (value: string | string[]) => void = Omitted — Called when a user changes selection.; id?: string = Generated — Input ID for label association.; placeholder?: string = Select… — Text shown for an empty selection.; emptyMessage?: SelectEmptyProps = { message: 'No options found' } — Empty results text and optional decorative icon.; size?: BaseSize = medium — Control and option size.; disabled?: boolean = false — Disable the control and close the popup.; variant?: Exclude = soft — Neutral or soft input appearance.; wide?: boolean = false — Fill the available input width. ## icon Render Material Symbols by name, with inherited or explicit size and color, optional fill, and accessible labels. Load the Material Symbols font through Theme or your app's font-face declaration. ```svelte ``` Load Material Symbols through Theme or a font-face declaration before rendering icons. Omit label for decorative icons; provide label for meaningful standalone icons. Size and color inherit when omitted. Set filled for the filled glyph. Native span attributes are forwarded. Props: name: IconName = — — Material Symbols identifier.; filled?: boolean = false — Use the filled glyph variant.; label?: string = Omitted — Accessible name for a meaningful standalone icon.; size?: Size = Inherited — x-small, small, medium, large or x-large.; color?: Color = Inherited — primary, secondary, foreground, background, muted, info, success, warning or error. ## surface A semantic flex container with theme tints, opt-in glass, shared spacing, corner rounding and optional scrolling. ```svelte Details Content inside the surface. ``` ```svelte Save ``` ```svelte Content ``` Use as to choose a semantic div, section or span. Native attributes, events and children are forwarded. Choose orientation, spacing and dimensions for layout, then variant, color, glass, shadow and radius for appearance. Scroll regions need a constrained parent height and an accessible name. The surface helper provides typed props for reuse. Props: as?: 'div' | 'section' | 'span' = div — Native root element.; children?: Snippet = Omitted — Content rendered directly inside the root.; color?: Color = background — Theme color; the shared recipe supplies content color.; variant?: Variant = neutral — Lightly tinted neutral, opaque tinted soft, or opaque filled panel.; spacing?: Size = Omitted — Shared padding and gap; omitted means zero.; orientation?: Orientation = vertical — Column, or row with centered cross-axis alignment.; width?: Dimension = fill — fill uses 100%; fit hugs content.; height?: Dimension = fit — fit uses natural height; fill uses 100% of a sized parent.; radius?: Size | `${number}rem` | `${number}%` = Omitted (0) — Named corner scale or an explicit rem/percentage radius.; shadow?: BaseSize | boolean = false — Shadow strength; true selects medium.; hover?: BaseSize = Omitted — Optional hover/focus treatment; does not make the root interactive.; scroll?: boolean = false — true sets overflow to auto; otherwise overflow stays visible.; glass?: boolean = false — Enable translucent paint and backdrop blur. ## theme Set up semantic palettes, native styles, surfaces, glass and icon fonts at the app root. ```svelte Theme mode, (next) => mode = next as ThemeMode} /> ``` Render Theme once at the app root to install semantic color tokens, surfaces, glass, fonts and native styles. Supply a partial palette of hex colors or separate light/dark palettes. Children are optional. ThemeModeToggle sets color-scheme metadata; mode is a controlled prop, not a binding. Override CSS tokens explicitly when customizing. Prebuilt Theme components from bref-ui-themes/new-paris, bref-ui-themes/glassy, bref-ui-themes/crystal-code and bref-ui-themes/vscode accept the same ThemeProps. They reuse the palette serializer and mode styles from core Theme. Their palette overrides merge per mode with their own defaults and stay scoped to each wrapper, including nested instances. Use ThemeModeToggle for light/dark/system selection or a local data-theme="light", "dark" or "auto" container; the nearest container wins. Without a mode selection, Crystal Code follows the system, New Paris and Glassy stay light, and VS Code stays dark. Theme-specific material and typography tokens remain unchanged. Props: palette?: Palette | { dark: Palette; light: Palette } = {} — Optional semantic hex colors; a shared palette applies to both modes. Invalid hex values throw.; children?: Snippet — Optional application content. ## theme-mode-toggle Set color-scheme metadata for an app theme control. ```svelte Appearance System Light Dark ``` Render once at the app root. This component emits color-scheme metadata and has no visible control. Pass a reactive mode prop; auto allows the system preference, light and dark force a scheme. Build a labeled native control to update mode. The mode prop is not bindable. Props: mode?: 'light' | 'dark' | 'auto' = auto — light, dark or auto; controls color-scheme metadata. ## checkbox A compact checkbox with clear checked states and native form behavior. ```svelte Accept terms ``` Wrap in a label or connect a label with for/id. Bind checked; pass indeterminate for a mixed state (not bindable). Native checkbox attributes, form submission, required, disabled and change/input events are preserved. Customize size; keep a visible keyboard focus indicator. Props: size?: Size = medium — Checkbox size from x-small through x-large.; checked?: boolean = false (bindable) — Bind to the checked state. Checkmark motion respects reduced motion and does not delay removing a parent. ## switch A checkbox-based on/off control with native form behavior. ```svelte {#if enabled}{:else}{/if} Notifications ``` Use a visible label for the native checkbox. Bind checked for state; name, required, disabled and native events retain form semantics. Children are an optional decorative snippet; keep the control accessible independently of its icon. Customize with scoped CSS and existing theme tokens. Props: checked?: boolean = false (bindable) — Bindable on/off state.; size?: BaseSize = medium — small, medium or large.; children?: Snippet = Omitted — Decorative content rendered inside the thumb. ## progress Show determinate or indeterminate progress, with an optional controlled seek control. ```svelte value = next} label="Playback position" /> ``` Use normalized values from 0 to 1; omit value for indeterminate progress. Provide label for the accessible name. Supplying onSeek switches to a native range control and reports normalized values; update value in the handler. disabled affects seeking. Native attributes/events are forwarded. Customize size and inherited color with CSS. Props: label?: string = — — Optional accessible name of the indicator or seek control.; value?: number = Omitted — Normalized value from 0 to 1. Omit for indeterminate progress.; onSeek?: (value: number) => void = Omitted — Makes progress seekable and emits normalized values on edits.; disabled?: boolean = false — Disables the seek control when present.; size?: BaseSize = medium — Track thickness: small, medium, or large. ## spinner Show loading status or a decorative animated ring. ```svelte ``` ```svelte ``` Provide label to announce loading status; omit it for a decorative ring hidden from assistive technology. Size and color inherit by default. Only label and size are accepted. Customize size or inherited CSS color; motion respects reduced-motion preferences. Props: label?: string = — — Optional screen reader status text; omit for a decorative ring.; size?: Size = Inherited — Matches Icon sizes; omitted size inherits surrounding font size. ## dialog Present modal content with native focus and accessible naming. ```svelte open = true} /> Display name ``` Bind open to show or dismiss the native modal dialog. header.title names the dialog and header.description describes it. Children supply body content; footer accepts a snippet or primary/secondary actions. The modal manages focus, traps keyboard navigation and restores focus on close. dismissible controls Escape and the close button. Native dialog attributes/events are forwarded except managed open/children/naming props. Customize size and theme tokens. Props: header: DialogHeaderDataProps = — — Title, optional description, and optional decorative icon. Title/icon changes animate unless reduced motion is requested.; children: Snippet = — — Dialog body.; open?: boolean = false (bindable) — Bindable modal state.; footer?: Snippet | { primary: DialogActionProps; secondary: DialogActionProps } = Omitted — Custom footer or exactly two actions; each action accepts label, icon, onClick, disabled, and status color.; dismissible?: boolean = true — Allow Escape and show the close button.; size?: Size | 'full-screen' = medium — Dialog width or full-screen; screens up to 36rem always use full-screen. ## popover An anchored native popover whose trigger snippet renders the owning control or component. ```svelte Wide input {#snippet trigger()} open = true} onclick={() => open = true} /> {/snippet} Helpful details beside the input. ``` ```svelte {#snippet trigger()} open = !open} aria-expanded={open} /> {/snippet} Display name open = false} /> ``` Bind open and render the owning native control or component inside the trigger snippet. Supply aria-expanded and an accessible name on that control. The component wires popover targeting, supports light dismissal and Escape, and closes when disabled. Children supply panel content. Customize supported Surface appearance/layout props; arbitrary native attributes are not accepted. Props: trigger: Snippet = — — The owning control or component; manages its own events and accessibility.; children: Snippet = — — Parameterless content inside the popover.; open?: boolean = false (bindable) — Bindable visibility; native dismissals update it.; disabled?: boolean = false — Keep the panel closed; the trigger controls its own disabled state.; as?: 'div' | 'section' | 'span' = div — Native root element of the Surface inside the panel.; variant?: Variant = soft — neutral, soft or filled; every variant uses glass.; color?: Color = background — Theme role for panel paint.; shadow?: BaseSize | boolean = medium — Shadow strength; true means medium and false disables it.; hover?: BaseSize = Omitted — Optional hover treatment strength.; spacing?: Size = medium — Padding and gap from x-small to x-large.; orientation?: Orientation = vertical — Horizontal or vertical Surface layout.; width?: Dimension = Omitted — fill follows trigger width; fit or omitted grows with content, at least as wide as the trigger.; height?: Dimension = Omitted — fit follows content; fill fills available Surface height within the viewport cap.; radius?: SurfaceRadius = small — Size token, rem value or percentage.; scroll?: boolean = false — Enable scrolling within the Surface.; class?: string = Omitted — Additional Surface classes.; style?: string = Omitted — Inline styles on the Surface. ## text-input A native single-line text control with an optional leading icon. ```svelte Name ``` Wrap in a label or connect one with for/id. Bind value as a string, including number inputs. Native input attributes and events are forwarded; onChange receives the string once per edit. Use type, name, required, readonly and disabled as on an input. Customize size, variant, glass, wide and an optional decorative icon. Props: value?: string = Omitted (bindable) — Bindable string value.; onChange?: (value: string) => void = Omitted — Called once per input edit.; icon?: IconProps = Omitted — Decorative leading icon.; size?: BaseSize = medium — Small, medium or large.; variant?: Exclude = soft — Neutral or soft surface treatment.; glass?: boolean = false — Translucent surface with backdrop blur.; wide?: boolean = false — Fills available width. ## text-area A native multiline text control with an optional leading icon. ```svelte Message ``` Wrap in a label or connect one with for/id. Bind value as a string. Native textarea attributes and events, including rows, name, required, readonly and disabled, are forwarded. onChange receives each edited value. Customize size, variant, glass, wide and the decorative leading icon. Props: value?: string = Omitted (bindable) — Bindable string value.; onChange?: (value: string) => void = Omitted — Called once per input edit.; icon?: IconProps = Omitted — Decorative leading icon.; size?: BaseSize = medium — Small, medium or large.; variant?: Exclude = soft — Neutral or soft surface treatment.; glass?: boolean = false — Translucent surface with backdrop blur.; wide?: boolean = false — Fills available width.; resizable?: boolean = true — Allows vertical resizing. ## tree-view Nested items with expandable branches and selectable rows. ```svelte ``` Provide nested items with unique IDs and labels; optional sections group roots. Bind selection to a string for single selection or an array for multiple selection. Use label for the accessible tree name. Use Tab to focus native buttons and Enter/Space to activate selection or expansion. onDelete receives an ID; update items to remove it. A node snippet customizes content. Customize size and glass; only the documented props are accepted. Props: items: TreeItemProps[] = — — Nested items with id, label, optional icon, children and disabled. IDs must be unique across the component.; sections?: TreeSectionProps[] = [] — Ordered headers with id, label, optional description and icon, and their own items array.; label?: string = Tree view — Accessible name for the group of items.; size?: BaseSize = medium — small, medium or large.; glass?: boolean = false — Use glass on selected soft surfaces, including nested items.; selection?: string | string[] = Omitted (bindable) — Bindable selected IDs. A string selects one item; an array toggles individual items independently.; defaultExpanded?: boolean = false — Sets the initial open state of each branch.; onDelete?: (id: string) => void = Omitted — Shows a delete button for each item; the caller updates the nested data and selection.; node?: Snippet<[TreeItemProps]> = Omitted — Replaces each top-level node in items and sections. The snippet owns its links, children, expansion, selection and actions. ## pill A compact glass label for status, categories and optional actions. ```svelte ``` Use label for visible text and an optional icon for decoration. onClick makes the label actionable; onDelete adds a separately named remove control. Children replace the label content. Customize size, variant, color, glass and wide. Native container attributes are forwarded; use explicit accessible labels for icon actions. Props: label: string = — — Visible label.; icon?: Omit = Omitted — Decorative leading icon.; children?: Snippet = Omitted — Visible content.; size?: Size = medium — Five sizes from x-small to x-large.; variant?: Variant = neutral — neutral, soft or filled.; color?: Exclude = foreground — Theme role.; onClick?: (event: MouseEvent) => void = Omitted — Activate the Pill.; onDelete?: () => void = Omitted — Show a labeled remove button.; wide?: boolean = false — Fill the available width.; swoosh?: boolean = false — Animate the highlight.; glass?: boolean = false — Translucent paint and backdrop blur. ## pill-group A list of Pills for related categories or statuses. ```svelte ``` Provide items with stable unique IDs and visible labels. onDelete receives the item ID; update items to remove it. Native list attributes are forwarded. Customize size, variant, color and glass; keep labels readable at narrow widths. Props: items: readonly PillDataProps[] = — — Items with unique IDs, labels and optional icons.; onDelete?: (id: string) => void = Omitted — Show delete buttons and report the item ID; the consumer updates items.; size?: Size = medium — Pill size.; variant?: Variant = neutral — neutral, soft or filled.; color?: Exclude = foreground — Theme color shared by the Pills.; glass?: boolean = false — Translucent paint and backdrop blur for every Pill. ## pill-choice-group Single or multiple choices presented as a group of Pills. ```svelte ``` Bind selection to a string for single selection or an array for multiple selection. Provide unique item IDs and labels. Native radio/checkbox behavior provides keyboard selection; label the group with aria-label or aria-labelledby. onDelete receives an ID; update items and selection together. Customize size, variant, color, glass and animateSelected. Props: items: readonly PillDataProps[] = — — Choices with unique IDs and visible labels; icons are optional.; selection: string | string[] = — (bindable) — Bindable ID for radio choice, or IDs for checkboxes.; disabled?: boolean = false — Disable every choice.; onDelete?: (id: string) => void = Omitted — Show delete buttons and report the item ID; the consumer updates items and selection.; size?: Size = medium — Pill size.; variant?: Exclude = neutral — Neutral selects soft; soft selects filled.; color?: Exclude = foreground — Theme role for every pill, including selected choices.; animateSelected?: boolean = false — Enable the pill highlight animation.; glass?: boolean = false — Translucent paint and backdrop blur for the choices. ## select Choose one or more labeled options by ID. ```svelte Status ``` Selected values are option IDs: bind a string for single selection or an array for multiple selection. Provide unique item IDs and visible labels; option icons and disabled states are optional. Give the trigger an accessible name through its placeholder. Use Tab to focus native option buttons, Enter/Space to select and Escape to close. Customize size, placeholder and emptyMessage. Select accepts only the documented props; use Combobox for searchable native form integration. Props: items: readonly SelectOptionDataProps[] = — — Unique IDs, labels, optional icons and disabled state.; value?: string | string[] = undefined (bindable) — Bindable selected ID or IDs; an array enables multiple selection.; onChange?: (value: string | string[]) => void = Omitted — Called when a user changes selection.; id?: string = Omitted — Trigger ID for label association.; placeholder?: string = Select… — Text shown for an empty selection.; emptyMessage?: SelectEmptyProps = { message: 'No options found' } — Empty results text and optional decorative icon.; size?: BaseSize = medium — Control and option size.; disabled?: boolean = false — Disable the control and close the popup. ## tabs Switch between sections with primary-colored floating pills and soft glass selection, horizontally or vertically. ```svelte {#if value === 'overview'} Workspace overview {:else} Workspace settings {/if} ``` ```svelte {#if value === 'overview'} Workspace overview {:else} Workspace settings {/if} ``` Items require unique IDs, labels and icon names. Bind value to the selected ID and render the associated content in the consumer. Omitted value preserves native Tab order; an unavailable selection leaves the first enabled tab focusable without changing value. Arrow keys follow orientation; Home/End move to endpoints. Set label for the tab list. width is horizontal-only; vertical rejects it. Customize size, filled and indicator transitions. Labels adapt to narrow screens; glass respects contrast and transparency preferences. Props: items: readonly TabItemDataProps[] = — — Display order; each item has a unique id, label, icon and optional disabled flag.; orientation?: Orientation = horizontal — Soft glass pills in a horizontal row or equal-width vertical column; determines arrow-key navigation.; width?: Dimension = fit — Horizontal only: fit keeps natural item widths and scrolls; fill spans the parent and truncates labels. Vertical rejects width.; size?: BaseSize = medium — Scales tab height, padding, label and icon in both orientations. Coarse pointers keep 44px touch targets.; value?: string = undefined (bindable) — Bindable selected ID. If missing or disabled, the first enabled tab stays focusable without changing the value. Omitted values preserve native Tab order.; onChange?: (id: string) => void = Omitted — Called once when user interaction changes selection.; label?: string = Tabs — Accessible name for the tab list.; filled?: boolean = false — Fill every Material Symbols icon; the selected icon is always filled. Does not change the soft glass background.; transitionIn?: TabTransition = Shared crossfade — Custom intro for the selected indicator; receives its HTMLElement.; transitionOut?: TabTransition = Shared crossfade — Custom outro for the selected indicator; receives its HTMLElement.
Content inside the surface.
Helpful details beside the input.
Workspace overview
Workspace settings