Svelte Multi-Filter Store

A lightweight, type-safe multi-dimensional filter store for Svelte 5 applications. This package provides a reactive way to handle complex filtering scenarios with multiple interdependent criteria.

Demo

Features

• 🎯 Type-safe: Built with TypeScript for robust type checking
• ⚡ Reactive: Built for Svelte 5 with runes
• 🔄 Interdependent Filters: Smart handling of filter dependencies
• 🎨 Framework Agnostic UI: Bring your own components
• 📦 Zero Dependencies: Only requires Svelte as a peer dependency

Installation

Using Bun (recommended):

bunx jsr add @zshzebra/svelte-multi-filter

Using npm:

npx jsr add @zshzebra/svelte-multi-filter

Using pnpm:

pnpm dlx jsr add @zshzebra/svelte-multi-filter

Quick Start

import { createFilterStore, type FilterConfig } from '@zshzebra/svelte-multi-filter';

// Define your data structure
interface Product {
    category: 'Shirt' | 'Pants' | 'Jacket';
    color: 'Red' | 'Blue' | 'Black';
}

// Your data
const products = [
    { category: 'Shirt', color: 'Red' },
    { category: 'Pants', color: 'Blue' },
    { category: 'Shirt', color: 'Black' }
];

// Configure filter options
const config = {
    category: ['Shirt', 'Pants', 'Jacket'],
    color: ['Red', 'Blue', 'Black']
} satisfies FilterConfig<Product>;

// Create the filter store
const filter = createFilterStore(products, config);

Usage in Svelte 5 Components

<script lang="ts">
    import {
        createFilterStore,
        type FilterConfig,
        type FilterDimension
    } from '@zshzebra/svelte-multi-filter';

    interface Product {
        category: 'Shirt' | 'Pants' | 'Jacket';
        color: 'Red' | 'Blue' | 'Black';
    }

    const products = [
        { category: 'Shirt', color: 'Red' },
        { category: 'Pants', color: 'Blue' },
        { category: 'Shirt', color: 'Black' }
    ];

    const config = {
        category: ['Shirt', 'Pants', 'Jacket'],
        color: ['Red', 'Blue', 'Black']
    } satisfies FilterConfig<Product>;

    const filter = createFilterStore(products, config);

    // State for dimensions and results
    let dimensions = $state<{
        category: FilterDimension<string>;
        color: FilterDimension<string>;
    }>();
    let results = $state<Product[]>([]);
    let availableCategoryOptions = $state<string[]>([]);
    let availableColorOptions = $state<string[]>([]);

    // Subscribe to store changes
    filter.subscribe((dims) => {
        dimensions = dims;
    });

    // Subscribe to filtered items
    filter.filteredItems.subscribe((items) => {
        results = items;
    });

    // Subscribe to available options
    filter.getAvailableOptions('category').subscribe((options) => {
        availableCategoryOptions = options;
    });

    filter.getAvailableOptions('color').subscribe((options) => {
        availableColorOptions = options;
    });
</script>

<div class="filters">
    <!-- Category Filter -->
    <div class="filter-group">
        <h3>Category</h3>
        <label>
            <input
                type="radio"
                name="category"
                value="Any"
                checked={dimensions?.category?.selected === 'Any'}
                onchange={() => filter.select('category', 'Any')}
            />
            Any
        </label>

        {#each config.category as option}
            <label>
                <input
                    type="radio"
                    name="category"
                    value={option}
                    checked={dimensions?.category?.selected === option}
                    disabled={!availableCategoryOptions.includes(option)}
                    onchange={() => filter.select('category', option)}
                />
                {option}
            </label>
        {/each}
    </div>

    <!-- Color Filter -->
    <div class="filter-group">
        <h3>Color</h3>
        <label>
            <input
                type="radio"
                name="color"
                value="Any"
                checked={dimensions?.color?.selected === 'Any'}
                onchange={() => filter.select('color', 'Any')}
            />
            Any
        </label>

        {#each config.color as option}
            <label>
                <input
                    type="radio"
                    name="color"
                    value={option}
                    checked={dimensions?.color?.selected === option}
                    disabled={!availableColorOptions.includes(option)}
                    onchange={() => filter.select('color', option)}
                />
                {option}
            </label>
        {/each}
    </div>
</div>

<button onclick={() => filter.reset()}>Reset Filters</button>

<div class="results">
    <h3>Results ({results.length})</h3>
    {#each results as item}
        <div>{JSON.stringify(item)}</div>
    {/each}
</div>

API Reference

createFilterStore<T>

Creates a new filter store for items of type T.

function createFilterStore<T extends Record<string, any>>(
    items: T[],
    config: FilterConfig<T>
): FilterStore<T>;

Parameters

• items: Array of items to filter
• config: Configuration object containing arrays of possible values for each dimension

Returns

A filter store object with the following methods and properties:

• subscribe: Subscribe to dimension state changes
• select: Update a dimension's selected value
• getAvailableOptions: Get a derived store of available options for a dimension
• filteredItems: Derived store of filtered items based on current selections
• reset: Reset all selections to 'Any'

Types

export type FilterDimension<T> = {
    options: T[];
    selected: T | 'Any';
};

export type FilterConfig<T extends Record<string, any>> = {
    [K in keyof T]: T[K][];
};

TypeScript Support

The package is written in TypeScript and includes full type definitions. Generic types allow for type-safe filtering of your data structures.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details