svelte-weave

A minimal, highly customizable Svelte component library — zero CSS framework required, zero configuration needed to look good.

Why svelte-weave?

Most Svelte UI libraries make you choose between two bad deals:

svelte-weave takes a different approach:

• Zero framework required. Drop a single CSS import and you're done. No tailwind.config.js changes, no CSS preprocessor, no purge setup. It works in plain Svelte, SvelteKit, or any build tool.
• One variable rethemes everything. Override --sw-primary and the entire primary color scale (50–950 shades, hover, active, foreground) updates automatically via color-mix() — no Sass, no build step.
• Dark mode that actually works. Three-layer system: OS preference respected with zero JS, manual override with a class, FOUC prevention built in. No flash, no jank, works on every edge runtime.
• Edge-runtime safe. No window or document access without guards. Deploys to Vercel, Netlify, and Cloudflare Pages out of the box.
• Svelte 4 classic syntax. Full compatibility with Svelte 4 apps and Svelte 5 apps (via the built-in legacy compat layer). No runes required.
• Optional Tailwind plugin. If you are on Tailwind, a single plugin import maps your entire Tailwind theme to --sw-* vars so components match your design system automatically.

Installation

npm install svelte-weave

Peer dependency: Svelte 4 or later.

Quick Start

1. Import the stylesheet

// In your layout, root +layout.svelte, or global CSS entry point:
import 'svelte-weave/styles';

Or link it in src/app.html:

<link rel="stylesheet" href="/node_modules/svelte-weave/dist/styles/index.css" />

2. Use components

<script>
  import { Button, Input, Card, Alert } from 'svelte-weave';
</script>

<Card padded>
  <Input label="Email" placeholder="[email protected]" />
  <Button variant="primary" fullWidth>Sign in</Button>
</Card>

<Alert variant="success" title="All good!">Your changes were saved.</Alert>

3. (Optional) Add the FOUC-prevention script for dark mode

Paste this into src/app.html immediately before %sveltekit.head%:

<script>(function(){try{var t=localStorage.getItem('sw-theme');if(t==='dark'){document.documentElement.classList.add('dark');}else if(t==='light'){document.documentElement.classList.add('light');}else if(window.matchMedia('(prefers-color-scheme: dark)').matches){document.documentElement.classList.add('dark');}}catch(e){}})();</script>

This prevents a flash of the wrong theme on first load.

Component Library

Foundations

Form & Inputs

Feedback & Status

Navigation

Data Display

Overlays & Layout

Theme System

Theming

All component styles use --sw-* CSS custom properties. Override them in your own CSS to retheme the entire library.

One-line color retheme

:root {
  --sw-primary: #7c3aed;   /* violet — the whole 50–950 scale updates automatically */
  --sw-radius:  0.25rem;   /* sharper corners everywhere */
}

Full variable reference

Dark Mode

svelte-weave ships a complete three-layer dark mode system:

Using the theme store and toggle

<script>
  import { ThemeToggle, theme, resolvedTheme } from 'svelte-weave';
</script>

<!-- Drop-in toggle button -->
<ThemeToggle />

<!-- With system option (three-way: light → dark → system) -->
<ThemeToggle showSystem />

<!-- With a text label in the button -->
<ThemeToggle showSystem>Theme</ThemeToggle>

<!-- Programmatic control -->
<button on:click={theme.setDark}>Force dark</button>
<button on:click={theme.setSystem}>Follow OS</button>

<!-- Read the current value -->
<p>Current theme: {$resolvedTheme}</p>

Store API

import { theme, resolvedTheme } from 'svelte-weave';

theme.set('dark');      // set explicitly
theme.set('light');
theme.set('system');    // follow OS; removes localStorage entry
theme.toggle();         // flip light ↔ dark
theme.setDark();
theme.setLight();
theme.setSystem();

$theme          // 'light' | 'dark' | 'system'
$resolvedTheme  // 'light' | 'dark' — never 'system'

Animation System

Scroll reveal (use:reveal)

Animates an element in when it enters the viewport using IntersectionObserver. SSR-safe and honours prefers-reduced-motion.

<script>
  import { reveal } from 'svelte-weave';
</script>

<div use:reveal>Fades in on scroll (default: fadeIn)</div>
<div use:reveal={{ preset: 'slideUp', delay: 150 }}>Slides up with 150 ms delay</div>
<div use:reveal={{ preset: 'scaleIn', once: false }}>Re-animates on every re-entry</div>

Built-in reveal presets:

Options:

Click effects (use:clickEffect)

Short feedback animation triggered on every click. Works on any element or via the <Button clickEffect="..."> prop.

<script>
  import { clickEffect } from 'svelte-weave';
  import { Button } from 'svelte-weave';
</script>

<button use:clickEffect="ripple">Material ripple</button>
<Button clickEffect="bounce">Bounce on click</Button>

Built-in click presets:

Custom presets

import { registerRevealPreset, registerClickPreset } from 'svelte-weave';

// 1. Define your @keyframes + class in your own CSS
// 2. Register the name → class mapping:
registerRevealPreset('spinIn', { className: 'my-anim-spin' });
registerClickPreset('flash',   { className: 'my-click-flash' });

// 3. Use it:
//    <div use:reveal={{ preset: 'spinIn' }}>...</div>
//    <Button clickEffect="flash">Flash</Button>

CSS animation variables

:root {
  --sw-anim-duration:    400ms;
  --sw-anim-easing:      cubic-bezier(0.4, 0, 0.2, 1);
  --sw-anim-delay:       0ms;
  --sw-anim-distance:    1.5rem;
  --sw-anim-scale-from:  0.92;
  --sw-anim-blur-amount: 8px;
}

/* Stagger a list of cards */
.card:nth-child(1) { --sw-anim-delay: 0ms;   }
.card:nth-child(2) { --sw-anim-delay: 100ms; }
.card:nth-child(3) { --sw-anim-delay: 200ms; }

Icon System

Components that accept icons (Button, Input, etc.) take an IconInput — any of three forms:

<!-- SVG string inline -->
<Button iconLeft="<svg viewBox='0 0 24 24' fill='currentColor'><path d='M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z'/></svg>">
  Home
</Button>

<!-- Registered icon name (needs a resolver, see below) -->
<Button iconLeft="mdi:home" iconRight="mdi:arrow-right">Go Home</Button>

<!-- Svelte component -->
<Button iconLeft={HomeIcon}>Home</Button>

<!-- Standalone icon -->
<WeaveIcon icon="mdi:star" size={24} />
<WeaveIcon icon={StarIcon} class="text-yellow-500" />

Registering an icon resolver

Call this once at app startup (e.g. in your root +layout.svelte):

import { registerIconResolver } from 'svelte-weave';

const myIcons: Record<string, string> = { 'my:home': '<svg>...</svg>' };
registerIconResolver((name) => myIcons[name] ?? null);

With Iconify:

import { registerIconResolver } from 'svelte-weave';
import { getIcon, renderSVG } from '@iconify/utils';
import icons from '@iconify-json/mdi/icons.json';

registerIconResolver((name) => {
  if (!name.startsWith('mdi:')) return null;
  const data = getIcon(icons, name.slice(4));
  return data ? renderSVG(data) : null;
});

Tailwind CSS Integration (Optional)

If your project uses Tailwind, a single plugin import maps your Tailwind color theme to --sw-* vars automatically.

// tailwind.config.js
import { weavePlugin } from 'svelte-weave/tailwind';

export default {
  plugins: [weavePlugin],
};

Custom color mapping

import { createWeavePlugin } from 'svelte-weave/tailwind';

export default {
  plugins: [
    createWeavePlugin({
      primaryColor: 'violet',
      dangerColor:  'rose',
      successColor: 'emerald',
      warningColor: 'orange',
    }),
  ],
};

Utilities

cn(...classes) — class merge helper

Merges class strings, filtering falsy values. Useful for consumer-side class composition.

import { cn } from 'svelte-weave';

const cls = cn('base-class', condition && 'conditional', userClass);

use:clickOutside — click-outside Svelte action

Dispatches a clickoutside event when the user clicks outside the element. Useful for closing dropdowns or menus without a full <Modal>.

<script>
  import { clickOutside } from 'svelte-weave';
  let open = true;
</script>

<div use:clickOutside on:clickoutside={() => open = false}>
  <!-- dropdown content -->
</div>

Package Exports

svelte-weave           → components, theme system, icon system, animations, utilities
svelte-weave/tailwind  → Tailwind CSS plugin
svelte-weave/styles    → CSS custom properties + base reset

Dev & Contributing

# Start the component playground
npm run dev

# TypeScript + Svelte type checking
npm run check

# Build the publishable package → ./dist/
npm run package

# Build the SvelteKit demo app
npm run build

Compatible with npm, pnpm, yarn, and bun.

License

MIT © svelte-weave contributors