@classic-homes/theme-svelte

Svelte 5 components for the Classic Theme design system. Built on Bits UI primitives and styled with Tailwind CSS.

Installation

npm install @classic-homes/theme-svelte @classic-homes/theme-tokens

Setup

1. Configure Tailwind CSS

Add the Classic Theme preset to your tailwind.config.js:

import preset from '@classic-homes/theme-tailwind-preset';

export default {
  presets: [preset],
  content: [
    './src/**/*.{html,js,svelte,ts}',
    './node_modules/@classic-homes/theme-svelte/**/*.{html,js,svelte,ts}',
  ],
};

2. Import Design Tokens

Import the CSS tokens in your app's root CSS file:

@import '@classic-homes/theme-tokens/css';

Or in your root layout:

<script>
  import '@classic-homes/theme-tokens/css';
</script>

Usage

<script>
  import { Button, Card, CardHeader, CardTitle, CardContent } from '@classic-homes/theme-svelte';
</script>

<Card>
  <CardHeader>
    <CardTitle>Welcome</CardTitle>
  </CardHeader>
  <CardContent>
    <Button variant="default">Click me</Button>
  </CardContent>
</Card>

Components

Core UI

• Button - Buttons with variants (default, secondary, destructive, outline, ghost, link)
• Input - Text input field
• Textarea - Multi-line text input
• Label - Form labels
• Checkbox - Checkbox input
• Switch - Toggle switch
• Select - Dropdown select
• FormField - Combined label + input + error handling

Layout

• AppShell - Application wrapper with skip links and toast container
• DashboardLayout - Sidebar + header layout for dashboards
• PublicLayout - Header + footer layout for public pages
• FormPageLayout - Centered form page layout
• Sidebar - Navigation sidebar
• Header - Page header
• Footer - Page footer

Feedback

• Alert - Alert messages (default, destructive, success, warning, info)
• AlertDialog - Confirmation dialogs
• Dialog - Modal dialogs
• Toast - Toast notifications
• ToastContainer - Toast notification container
• Spinner - Loading spinner
• Skeleton - Loading skeleton

Data Display

• Card - Card container with header, content, footer
• Badge - Status badges
• DataTable - Sortable data table
• Tabs - Tab navigation
• Tooltip - Hover tooltips
• DropdownMenu - Dropdown menus
• Avatar - User avatars

Media

• AspectRatio - Constrains content to a fixed width-to-height ratio
• Image - Responsive image with lazy loading, placeholders, and error fallback
• Video - Video player with themed controls, full keyboard support, and HLS/Cloudflare Stream playback
• Audio - Compact audio player with themed controls
• MediaEmbed - Lazy YouTube, Vimeo, Cloudflare Stream, and Matterport 3D tour embeds that load nothing until clicked
• MediaGrid - Responsive gallery of media thumbnails
• MediaCarousel - Swipeable media slides with dots, thumbnails, and optional autoplay
• Lightbox - Full-screen media viewer with zoom, pan, and keyboard navigation

Adaptive streaming and Cloudflare Stream

Video plays HLS playlists, including Cloudflare Stream, with the same controls as a self-hosted file. Safari plays HLS natively; other browsers need hls.js, an optional peer dependency:

npm install hls.js

// once, at app startup
import { setHlsLoader } from '@classic-homes/theme-svelte';

setHlsLoader(() => import('hls.js').then((m) => m.default));

The import lives in your code rather than in this package, so consumers who never play a stream are not forced to install hls.js to build.

<script lang="ts">
  import { Video, cloudflareStream } from '@classic-homes/theme-svelte';

  const tour = cloudflareStream('a1b2c3d4e5f6', {
    customerCode: 'abc123',
    title: 'Product tour',
  });
</script>

<Video item={tour} />

cloudflareStream() derives the HLS playlist and poster from Stream's URL scheme with no API call. Pass a signed playback token in place of the video id for private videos. For Cloudflare's own player, use MediaEmbed with provider="cloudflare".

Branding

• LogoMain - Main logo component
• LoadingLogo - Animated loading logo

Notification Components (Optional)

Notification UI components are available via a separate entry point. This makes the @classic-homes/notifications dependency optional - you only need it if you use these components.

# Install the notifications package if using notification components
npm install @classic-homes/notifications

<script>
  // Import notification components from the /notifications subpath
  import {
    NotificationList,
    NotificationItem,
    NotificationBadge,
    NotificationDialog,
    NotificationFilters,
    NotificationBulkActions,
  } from '@classic-homes/theme-svelte/notifications';

  // Import types and utilities from the notifications package
  import type { Notification } from '@classic-homes/notifications/core';
</script>

Available notification components:

• NotificationBadge - Unread count badge
• NotificationItem - Single notification card
• NotificationList - List of notifications with empty state
• NotificationDialog - Detail dialog for a notification
• NotificationFilters - Filter tabs (all/read/unread)
• NotificationBulkActions - Bulk action toolbar

Error Handling

Overview

Components in this library do not include built-in error boundaries to give you full control over error handling. We recommend implementing error handling at your application's root level.

Recommended: Error Boundary Component

Create an ErrorBoundary component to catch and handle errors gracefully:

<!-- src/lib/ErrorBoundary.svelte -->
<script lang="ts">
  import type { Snippet } from 'svelte';
  import { Button, Alert, AlertDescription } from '@classic-homes/theme-svelte';

  interface Props {
    children: Snippet;
    fallback?: Snippet<[Error, () => void]>;
  }

  let { children, fallback }: Props = $props();
  let error = $state<Error | null>(null);

  function reset() {
    error = null;
  }

  $effect(() => {
    const handleError = (e: ErrorEvent) => {
      e.preventDefault();
      error = e.error || new Error(e.message);
    };

    const handleUnhandledRejection = (e: PromiseRejectionEvent) => {
      e.preventDefault();
      error = e.reason instanceof Error ? e.reason : new Error(String(e.reason));
    };

    window.addEventListener('error', handleError);
    window.addEventListener('unhandledrejection', handleUnhandledRejection);

    return () => {
      window.removeEventListener('error', handleError);
      window.removeEventListener('unhandledrejection', handleUnhandledRejection);
    };
  });
</script>

{#if error}
  {#if fallback}
    {@render fallback(error, reset)}
  {:else}
    <div class="flex min-h-screen items-center justify-center p-4">
      <div class="w-full max-w-md space-y-4">
        <Alert variant="destructive">
          <AlertDescription>
            <strong>Something went wrong</strong>
            <p class="mt-2 text-sm">{error.message}</p>
          </AlertDescription>
        </Alert>
        <Button onclick={reset} variant="outline" class="w-full">Try again</Button>
      </div>
    </div>
  {/if}
{:else}
  {@render children()}
{/if}

Usage with AppShell

Wrap your AppShell with the ErrorBoundary:

<!-- src/routes/+layout.svelte -->
<script>
  import { AppShell } from '@classic-homes/theme-svelte';
  import ErrorBoundary from '$lib/ErrorBoundary.svelte';
</script>

<ErrorBoundary>
  <AppShell>
    <slot />
  </AppShell>
</ErrorBoundary>

Custom Fallback UI

You can provide a custom fallback UI:

<ErrorBoundary>
  {#snippet fallback(error, reset)}
    <div class="error-page">
      <h1>Oops!</h1>
      <p>{error.message}</p>
      <button onclick={reset}>Reload</button>
    </div>
  {/snippet}

  <AppShell>
    <slot />
  </AppShell>
</ErrorBoundary>

Toast Notifications

The library includes a toast store for managing notifications:

<script>
  import { toastStore, Button } from '@classic-homes/theme-svelte';

  function showSuccess() {
    toastStore.success('Operation completed successfully!');
  }

  function showError() {
    toastStore.error('Something went wrong', { title: 'Error' });
  }
</script>

<Button onclick={showSuccess}>Show Success</Button>
<Button onclick={showError} variant="destructive">Show Error</Button>

Toast methods:

• toastStore.success(message, options?) - Green success toast
• toastStore.error(message, options?) - Red error toast (persistent by default)
• toastStore.warning(message, options?) - Yellow warning toast
• toastStore.info(message, options?) - Blue info toast
• toastStore.add(toast) - Add custom toast
• toastStore.remove(id) - Remove toast by ID
• toastStore.clear() - Remove all toasts

Sidebar State

For layouts with collapsible sidebars, use the sidebar store:

<script>
  import { sidebarStore } from '@classic-homes/theme-svelte';

  function toggleSidebar() {
    sidebarStore.toggle();
  }
</script>

<button onclick={toggleSidebar}>
  {sidebarStore.isOpen ? 'Close' : 'Open'} Sidebar
</button>

TypeScript Support

All components are fully typed. Import types as needed:

import type {
  NavItem,
  NavSection,
  User,
  Tab,
  FileMetadata,
  DataTableColumn,
  SelectOption,
} from '@classic-homes/theme-svelte';

Svelte 5 Runes

All components use Svelte 5 runes syntax:

• $props() for component props
• $state() for reactive state
• $derived() for computed values
• $effect() for side effects
• $bindable() for two-way binding

Accessibility

Components are built with accessibility in mind:

• Proper ARIA attributes
• Keyboard navigation support
• Focus management
• Screen reader friendly
• Skip links in AppShell

License

MIT