fuz_ui

fuz_ui is a Svelte UI library with components and helpers for making zippy websites. It's built on fuz_css and provides a documentation system built on svelte-docinfo. fuz_ui emphasizes capability and efficiency and tries to be simple for those goals.

To import the Svelte components:

See the nav for the available components and other helpers.

mdz is a markdown dialect enhanced with Svelte components, autolinked identifiers, and other integrations. To compile static content at build time instead of parsing at runtime with slower dynamic rendering, use its preprocessor:

fuz_ui is part of the Fuz stack. See also the repo.

Fuz bases its theme support on fuz_css, which is based on semantic HTML and CSS custom properties. For usage docs see ThemeRoot.

Browse the full api docs.

vite_plugin_pkg_json is a Vite plugin that serves a publish-safe subset of your package.json as the virtual module 'virtual:pkg.json'. The default export is typed PkgJson from fuz_util, and contains package identity plus Fuz extension fields, with everything else excluded.

The plugin strips package.json to the allowlist and serves only that, so info like name/version/repository and the Fuz extension fields like logo are available to your code. The docs system around the content you're reading relies on it. Importing the root package.json directly instead inlines the whole file -- scripts, dependencies, private config -- into the client bundle and trips SvelteKit's server.fs.allow on a cold HMR reload; serving the curated subset avoids both.

Register the plugin, vite_plugin_pkg_json.ts:

The plugin uses enforce: 'pre' so any order works. For TypeScript it requires ambient declarations, like in src/app.d.ts:

You may then import the default export anywhere in client or server code:

fuz_ui has optional patterns that leverage the feature. One example is adding SiteState at the root layout, so glyph and repo_url come from package.json instead of being hardcoded:

It's also the curated pkg_json half of a LibraryJson rendered by LibraryDetail. The fuz_ui docs pattern combines it with the analyzed modules from virtual:svelte-docinfo (svelte-docinfo.fuz.dev):

By default the plugin keeps only the keys in pkg_json_keys, including package identity values and some Fuz extension fields. Everything else is dropped:

• name
• version
• private
• description
• tagline: Fuz extension, like description but snappier
• glyph: Fuz extension, emoji or character icon
• logo: Fuz extension, logo image path
• logo_alt: Fuz extension, logo alt text
• license
• homepage
• repository
• funding
• exports

The set of picked fields defaults to pkg_json_keys, and you can extend or replace them:

Because library_json_from_modules re-strips at runtime, the same list must reach all three places (the plugin, that runtime call, and the virtual:pkg.json ambient type), or the extras get dropped:

For type safety, widen the src/app.d.ts ambient type to match -- the same custom_keys const drives it via Pick over PackageJson:

Fuz supports SvelteKit's config for Content Security Policies with the create_csp_directives helper. Fuz also provides related helpers, types, and CSP data.

The API is designed to read as an audit log: every user-added source is named at exactly one site in the source code. There's no implicit promotion of sources across directives. If you want a domain on script-src, you write script-src. Library defaults are inherited unless you opt out via replace_defaults.

Example usage:

Three stages run in order, and each is independent. Use the one that matches your intent.

1. CreateCspDirectivesOptions replace_defaults — the starting state. Omitted, it's csp_directive_value_defaults. Provided, it replaces the library defaults wholesale: exactly the directives you list, nothing inherited. {} starts blank; null throws (avoid the null/undefined footgun where a conditional silently disables defaults).
2. extend — sources to append per directive, layered left to right. Values append (and deduplicate) to the result of replace_defaults and prior entries. Boolean directives (e.g. upgrade-insecure-requests) are excluded by the type. Only array-typed directives can be extended. Compose multiple shared maps in one array.
3. overrides — final-pass per-directive replace or remove. Highest precedence. Pass null to drop a directive from the output entirely.

extend is the common path: take a starting state and add per-directive sources. Sources land only on the directives you name. There's no cross-directive promotion.

Multiple entries compose left to right, deduplicating across layers. Useful for combining a "shared lib" object with app-specific extras:

Default-deny directives (those whose default value is ['none'], including default-src, object-src, base-uri, script-src-attr, and child-src) cannot be extended. Attempting to extend them throws. Opting in must go through replace_defaults or overrides so the opt-in is visible at the call site. Note that overrides cannot rescue an extend for a default-deny directive in the same call: extend runs first and throws before overrides would replace the value. Move the sources into overrides directly, or opt in via replace_defaults and then extend.

The final-pass overrides option replaces a directive's value or removes it entirely. Highest precedence. Wins over replace_defaults and extend.

replace_defaults sets the starting state. The default is the library's curated csp_directive_value_defaults. To use your own foundation, pass a complete map. Anything you don't list is absent from the starting state, including security defaults like default-src: ['none']. Use extend and overrides for per-directive tweaks while keeping the library defaults.

Use overrides for tweaks (replace one directive while keeping the library defaults), and replace_defaults for full ownership of the starting state. null is rejected (top-level or per-key). Omit the option for library defaults, pass {} to start blank, or use overrides to remove a specific directive.

create_csp_directives validates inputs and outputs at build time. Misconfigurations throw rather than producing a silently broken policy.

• Unknown directive keys in any of replace_defaults, extend, or overrides throw with the offending name.
• Extending a directive whose current value is ['none'] throws. Opt in via replace_defaults or overrides instead.
• null for replace_defaults (top-level or per-key) throws. Omit the option for library defaults, pass {} to start blank, or use overrides to remove a specific directive.
• null per-key in extend throws with a pointer to overrides. extend only appends, so removal lives on overrides.
• undefined per-key in any of the three stages is treated as omitted (no-op). This lets conditional patterns like {'connect-src': is_prod ? [API_URL] : undefined} work naturally.
• Non-object entries in extend (e.g. extend: [undefined]) throw a library error pointing at the option, instead of a cryptic native TypeError.
• The output is validated to ensure 'none' never appears alongside other tokens (an invalid CSP that browsers reject).
• The output is validated to ensure no directive ends up with an empty array. Use ['none'] to forbid all sources, or omit the directive entirely. Empty arrays can be silently dropped or fall back to default-src, widening the policy.
• Source arrays are validated to contain only strings. Non-string elements (slipped through via as any) would render as undefined or [object Object] in the emitted header.

The exported csp_directive_specs has JSON data about the CSP directives. Fuz omits deprecated directives.

The intersect helper in intersect.svelte.ts creates an attachment that observes when an element enters or leaves the viewport using the Intersection Observer API.

Uses the lazy function pattern to optimize reactivity: callbacks can update without recreating the observer, preserving state.

The callback receives intersecting (boolean), intersections (number count), el, observer, and disconnect.

Triggers when the element enters the viewport by at least a pixel. Scroll to see items change state.

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Triggers when 50% of the element is visible.

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Triggers only when the element is fully visible.

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Disconnects after the first intersection cycle (enter and leave). A count of 0 disables observation. Negative or undefined never disconnects. (the default)

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Disconnects after two intersection cycles.

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Try different parameter combinations. Positive count values disconnect after N cycles. 0 disables observation. Negative or undefined never disconnects. (the default)

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Fuz includes a number of icons available as data that can be mounted with the Svg component. Only the ones you use are included in your bundle.

• action
• action_local_call
• action_remote_notification
• action_request_response
• add
• arrow_left
• arrow_right
• backend
• cancel
• capability
• chat
• checkmark
• checkmark_heavy
• chevron_down
• chevron_left
• chevron_right
• chevron_up
• clear
• close
• connect
• copy
• create_directory
• create_file
• delete
• desk
• directory
• disconnect
• domain
• double_chevron_left
• double_chevron_right
• download
• drag
• edit
• error
• external_link
• file
• heartbeat
• idea
• important
• info
• link
• list
• log
• model
• page
• part
• paste
• pause
• pin
• ping
• placeholder
• play
• preview
• project
• prompt
• provider
• refresh
• remove
• reset
• response
• restore
• retry
• send
• session
• settings
• sort
• space
• stop
• tab
• terminal
• thread
• turn
• unknown
• upload
• view
• workspace
• xmark
• xmark_heavy

Fuz includes a number of logos available as data that can be mounted with the Svg component. Only the ones you use are included in your bundle.

• <Svg data={logo_fuz} />
• <Svg data={logo_fuz_ui} />
• <Svg data={logo_fuz_css} />
• <Svg data={logo_fuz_template} />
• <Svg data={logo_fuz_code} />
• <Svg data={logo_fuz_blog} />
• <Svg data={logo_fuz_mastodon} />
• <Svg data={logo_fuz_gitops} />
• <Svg data={logo_fuz_util} />
• <Svg data={logo_gro} />
• <Svg data={logo_tsv} />
• <Svg data={logo_github} />
• <Svg data={logo_mdn} />

icon can be a string prop or snippet:

Alerts can be buttons by including an onclick prop. This API may change because it's a bit of a mess - a separate AlertButton may be better.

clicks: 0

The status prop, which defaults to 'inform', changes the default icon and color.

The root link defaults to the site_context icon, rendered as an Svg. Set the SiteState once at your app's root layout and every Breadcrumb picks it up. It falls back to the site_context glyph, then a bullet.

Fuz provides a customizable contextmenu that overrides the system contextmenu to provide helpful capabilities to users. Popular websites with similar features include Google Docs and Discord. Below are caveats about this breaking some user expectations, and a workaround for iOS Safari support. See also the contextmenu_event docs and w3 spec.

When you rightclick inside a ContextmenuRoot, or longpress on touch devices, it searches the DOM tree for behaviors defined with Contextmenu starting from the target element up to the root. If any behaviors are found, the Fuz contextmenu opens, showing all contextually available actions. If no behaviors are found, the default system contextmenu opens.

Here's a ContextmenuRoot with a Contextmenu inside another Contextmenu:

This simple hierarchical pattern gives users the full contextual actions by default -- not just the actions for the target being clicked, but all ancestor actions too. This means users don't need to hunt for specific parent elements to find the desired action, unlike many systems -- instead, all actions in the tree are available, improving UX convenience and predictability at the cost of more noisy menus. Developers can opt out of this inheritance behavior by simply not nesting Contextmenu declarations, and submenus are useful for managing complexity.

Mouse and keyboard:

• rightclick opens the Fuz contextmenu and not the system contextmenu (minus current exceptions for input/textarea/contenteditable)
• holding Shift opens the system contextmenu, bypassing the Fuz contextmenu
• keyboard navigation and activation should work similarly to the W3C APG menubar pattern

Touch devices:

• longpress opens the Fuz contextmenu and not the system contextmenu (minus current exceptions for input/textarea/contenteditable)
• tap-then-longpress opens the system contextmenu or performs other default behavior like selecting text, bypassing the Fuz contextmenu
• tap-then-longpress can't work for clickable elements like links; longpress on the first contextmenu entry for those cases (double-longpress)

All devices:

• opening the contextmenu on the contextmenu itself shows the system contextmenu, bypassing the Fuz contextmenu
• opening the contextmenu attempts haptic feedback with navigator.vibrate

Check the boxes below to disable automatic a link detection and copy text detection, and see how the contextmenu behaves.

When no behaviors are defined, the system contextmenu is shown instead.

Expected: the Fuz contextmenu will open and show:

• custom "some custom entry" entry
• "copy text" entry when text is selected
• link entry when clicking on a link

Fuz provides two versions of the contextmenu root component with different tradeoffs due to iOS Safari not supporting the contextmenu event as of October 2025, see WebKit bug #213953.

Use ContextmenuRoot by default for better performance and haptic feedback. Use ContextmenuRootForSafariCompatibility only if you need iOS Safari support.

ContextmenuRoot

• standard, default implementation
• relies on the browser's contextmenu event
• much simpler, better performance with fewer and less intrusive event handlers, fewer edge cases that can go wrong
• does not work on iOS Safari until WebKit bug #213953 is fixed

ContextmenuRootForSafariCompatibility

• opt-in hacky alternative when iOS support is needed
• implements custom longpress detection to work around iOS Safari's lacking contextmenu event support
• degraded experience because some browsers (including mobile Chrome) block navigator.vibrate haptic feedback due to the timeout-based gesture detection (because it's not a direct user action)
• works on all devices including iOS Safari
• more complex implementation with custom touch event handling and gesture detection, may cause edge case UX problems on some devices
• a longpress is cancelled if you move the touch past a threshold before it triggers
• opt into this version only if you need iOS Safari support

The Fuz contextmenu provides powerful app-specific UX, but it breaks from normal browser behavior by replacing the system contextmenu.

To mitigate the downsides:

• The Fuz contextmenu only replaces the system contextmenu when the DOM tree has defined behaviors. Note that a links have default contextmenu behaviors unless disabled. Other interactive elements may have default behaviors added in the future.
• The Fuz contextmenu does not open on elements that allow clipboard pasting like inputs, textareas, and contenteditables -- however this may change for better app integration, or be configurable.
• To bypass on devices with a keyboard, hold Shift while rightclicking.
• To bypass on touch devices (e.g. to select text), use tap-then-longpress instead of longpress.
• Triggering the contextmenu inside the Fuz contextmenu shows the system contextmenu.

See also the contextmenu_event docs and the w3 spec.

The Details component is an alternative to the details element. By default it's lazy, and you can pass eager to render the children immediately like the base element.

Benefits of lazy children:

• children are transitioned in/out with an animation (TODO this may be doable with eager children, if so it would probably be the better default, and then the prop should be swapped to lazy)
• improved performance, can significantly improve UX in some cases

Tradeoffs:

• ctrl+f does not work to find text and auto-open the details
• you may desire some behavior caused by mounting the children

A Dialog is a modal that overlays the entire page. It uses the native dialog element, so opening it with showModal() puts children in the browser's top layer, escaping ancestor stacking (avoiding bugs and caveats, like unwanted overflow containment and cascading styles, without using Teleport). The native element also traps focus, makes the rest of the page inert, closes on Escape, and restores focus to the previously focused element on close.

Mounting the component opens the dialog, so the simplest usage guards it with {#if}. Wrap the content in an optional DialogContent for a padded, centered .pane card with a close button:

The {#if} guard isn't required. Pass show to let the component manage its own rendering (it defaults to true):

DialogContent is a .pane card that shrinks to fit its content, up to max_width. Tune it with class and other forwarded attributes, adjust the surrounding space with gutter and the inner space with padding, and toggle the card style with pane={false} for an unstyled surface:

DialogContent adds a close button in the top-right corner, rendered after the content so it doesn't take initial focus. Pass close_button={false} to remove it, or a snippet to render your own. The snippet receives attrs with type DialogCloseButtonAttrs with the default button's placement, styling, a11y, and the onclick that closes the dialog, plus the DialogContext. Spread attrs to inherit the corner-anchored button and override only the glyph, or ignore it to place the button freely:

DialogContent is optional. Pass children directly for full control of the surface:

By default the dialog is centered. Pass align="top" to anchor it near the top of the page and grow downward, which avoids the jumpiness of a centered dialog whose content changes height. Add and remove items in the demo to compare:

Tall content scrolls within the dialog rather than the page behind it:

Clicking outside the content closes the dialog by default. Pass dismissable={false} to disable click-outside (Escape and your own buttons still close it):

To intercept closing, pass onbeforeclose and return false to keep the dialog open, which is useful for confirming unsaved changes. Closing programmatically via show={false} bypasses it:

Dialogs can open more dialogs, each stacking in the top layer. The deepest level in this demo renders its own multi-pane surface via the bare-children path:

Docs is the top-level component behind fuz_ui's docs system, which is used to construct this page, and all of the other /docs pages in the Fuz stack. It has a three-column responsive layout with managed navigation and uses ordinary SvelteKit patterns: it takes an array of Tomes and renders the current page as children, so it lives in a +layout.svelte wrapping your docs routes.

It requires two contexts: site_context (a SiteState for components like Breadcrumb) set once at the root layout (typically the root, anywhere up the tree works), and library_context (a Library) set in the docs layout:

For live and complete examples, see the docs layouts in fuz_ui or fuz_css.

Library is the reactive wrapper around a LibraryJson. It's constructed from the package.json subset 'virtual:pkg.json' served by vite_plugin_pkg_json plus the analyzed modules from virtual:svelte-docinfo.

Set it into library_context at the docs layout. Docs reads it for navigation, and LibraryDetail and LibrarySummary render it:

These docs you're reading are the live example. fuz_ui sets its own Library as described above. See Docs for the surrounding layout, and LibraryDetail/LibrarySummary for the components that render it.

LibraryDetail renders the full metadata for a library and its repo, including its module and declaration index. See the Library for how to construct one from vite_plugin_pkg_json and virtual:svelte-docinfo:

It projects its library prop into library_context for its subtree, so the module and declaration links resolve against the rendered library even when it differs from the site's own. When rendering a foreign library, pass links_full so the links point at the library's deployed docs instead of site-local paths:

LibrarySummary renders a compact card for a library and its repo. See the Library for how to construct one from vite_plugin_pkg_json and virtual:svelte-docinfo:

The default animation has text children, so they scale with font-size.

Set size with custom properties:

Set size with classes:

Size is inherited by default:

with inline={true} •••

with children 🐢🐢🐢 * 2

with running={true}

and children

Preserves a button's normal width while animating.

toggle the pending status of the buttons below

do something async

Adds a redirect for a page using a meta tag with the refresh header. Includes a rendered link and JS navigation fallback.

redirect to /docs

Fills available space by default:

Set size: (see the fuz_css typography docs)

Set --font_size on the component or a parent:

Set fill: (see the fuz_css colors docs)

Set --text_color on the component or a parent, for svgs that have no default fill:

Define gradients on the data with gradients and reference them by id from a fill or stroke:

Relocates elements in the DOM, in the rare cases that's useful and the best solution. (like when you need to escape overflow containment or avoid inheriting styles without restructuring the component tree) Does not work with SSR.

ThemeRoot defaults to automatic color-scheme detection with prefers-color-scheme, and users can also set it directly:

Pass props to override the default:

The builtin themes support both dark and light color schemes. Custom themes may support one or both color schemes.

A theme is a simple JSON collection of fuz_css style variables that can be transformed into CSS that set custom properties. Each variable can have values for light and/or dark color schemes. In other words, "dark" isn't a theme, it's a mode that any theme can implement.

Themes are plain CSS that can be sourced in a variety of ways.

To use Fuz's base theme:

ThemeRoot can be customized with the the nonreactive prop theme_state:

ThemeRoot sets the theme_state in the Svelte context:

For a more complete example, see fuz_template.

ThemeRoot initializes the system's theme support. Without it, the page will not reflect the user's system color-scheme. By default, ThemeRoot applies the base theme to the root of the page via create_theme_setup_script. It uses JS to add the .dark CSS class to the :root element.

This strategy enables color scheme and theme support with minimal CSS and optimal performance for most use cases. The system supports plain CSS usage that can be static or dynamic, or imported at buildtime or runtime. It also allows runtime access to the underlying data like the style variables if you want to pay the performance costs. Scoped theming to one part of the page is planned.

The theme setup script interacts with sync_color_scheme to save the user's preference to localStorage. See also ColorSchemeInput.

The setup script avoids flash-on-load due to color scheme, but currently themes flash in after loading. We'll try to fix this when the system stabilizes.