Troubleshooting

A component renders without Fractalsvelte styling

The component import is working, but the shared stylesheet has not been loaded. Import the Fractalsvelte SASS entry point once in the root layout or application entry.

<script lang="ts">
	import 'fractalsvelte/styles/index.sass';
</script>

If the component uses utility classes such as gap16 or pad32, also configure fractals-styler and import its generated virtual stylesheet.

<script lang="ts">
	import 'virtual:fractals-styler.css';
</script>

Do not move either import into a leaf component: duplicate imports make style ownership hard to reason about and may produce inconsistent development behaviour.

Vite cannot resolve virtual:fractals-styler.css

The virtual stylesheet is created by the Vite plugin. Install fractals-styler, add it to vite.config.ts, then restart the dev server.

import { sveltekit } from '@sveltejs/kit/vite';
import fractalsStyler from 'fractals-styler';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [sveltekit(), fractalsStyler()]
});

If you do not intend to use Fractals Styler’s generated utilities, remove the virtual stylesheet import and avoid those classes in your own markup.

Sass cannot resolve the Fractalsvelte stylesheet

Install Sass as a development dependency in the consuming project, then make sure the import uses the package export exactly.

pnpm add -D sass

import 'fractalsvelte/styles/index.sass';

Use .sass, not .scss. Fractalsvelte styles are written in indented SASS.

TypeScript says a component is not exported

Import public components from the package root:

import { TreeView, Resizable } from 'fractalsvelte';

Do not import from the package’s internal src or dist paths. If a newly released component still appears unavailable, confirm that the application has installed the intended package version and restart the TypeScript server or dev server after updating dependencies.

bind: reports that a prop is not bindable

Only state props documented as bindable support two-way binding. For example, use bind:open with overlays and bind:value with value controls; do not try to bind presentation props such as variant or size.

<script lang="ts">
	import { Switch } from 'fractalsvelte';

	let enabled = $state(false);
</script>

<Switch bind:checked={enabled} />

Check the component page’s Props table for the exact binding name and type.

A compound component throws an error about its root

Compound parts must be descendants of their matching root. For example, DialogTrigger, DialogContent, and DialogClose belong inside DialogRoot.

<script lang="ts">
	import { DialogContent, DialogRoot, DialogTrigger } from 'fractalsvelte';
</script>

<DialogRoot>
	<DialogTrigger>Open</DialogTrigger>
	<DialogContent>Details</DialogContent>
</DialogRoot>

Do not place compound pieces in unrelated components or render them conditionally outside the root that provides their shared context.

An overlay does not open or close when application state changes

Bind its open state and change the bound variable, rather than trying to query or mutate the component’s internal DOM.

<script lang="ts">
	import { Sheet } from 'fractalsvelte';

	let open = $state(false);
</script>

<button onclick={() => (open = true)}>Filters</button>
<Sheet title="Filters" bind:open>Filter controls</Sheet>

For a compound overlay, bind open on the root component and keep the trigger/content under that root.

A Svelte 4-style event handler does not compile

Fractalsvelte targets Svelte 5. Use event attributes such as onclick, not the legacy on:click directive.

<Button onclick={save}>Save</Button>

Likewise, use $state for local reactive values in new Svelte 5 code.

A menu, tooltip, or popover is clipped

First check the containing layout for overflow: hidden, a constrained height, or a stacking context created by transforms. These are common causes of an anchored overlay being visually cut off. Move the trigger into an appropriate layout layer, loosen the clipping container, or use an overlay component whose placement better matches the workflow.

Tree View or Resizable does not update outside its own component

Bind the state that the parent needs to observe. TreeView exposes selected and expanded; Resizable exposes its first-panel size.

<script lang="ts">
	import { Resizable, TreeView } from 'fractalsvelte';

	let selected = $state('src');
	let size = $state(40);
</script>

<TreeView items={items} bind:selected />
<Resizable bind:size={size}>{/* first and second snippets */}</Resizable>

Keep tree item ids stable across renders. Changing ids causes the selected and expanded values to refer to nodes that no longer exist.

Styles look correct locally but not in a production build

Make sure fractals-styler scans the source files that contain your utility class names. Do not generate class names dynamically at runtime—for example, avoid `gap${amount}`—because a build-time scanner cannot see the final class. Use a fixed class, a conditional list of fixed classes, or a component-scoped SASS rule instead.

Installation fails because of incompatible runtime versions

Use Svelte 5 and Node.js 18.13.0 or newer. Remove duplicate or older Svelte installations from the consuming project’s dependency graph, reinstall dependencies, and rerun the application check.

pnpm install
pnpm check

For a SvelteKit application, use a current SvelteKit 2 release so the project’s Svelte and Vite integration stay aligned.