Skip to main content

Interactive Components Guide

How to integrate Preact interactive islands into your directory site.

Available Components​

The @ever-works/ui package includes 8 Preact components that run as Astro Islands:

ComponentImport PathPurpose
SearchInput@ever-works/ui/preact/SearchInputDebounced text search
FilterBar@ever-works/ui/preact/FilterBarCategory + tag toggle filters
SortSelect@ever-works/ui/preact/SortSelectSort dropdown
ThemeToggle@ever-works/ui/preact/ThemeToggleDark/light mode toggle
BackToTop@ever-works/ui/preact/BackToTopScroll-to-top button
LayoutSwitcher@ever-works/ui/preact/LayoutSwitcherGrid/list/compact view toggle
MobileMenu@ever-works/ui/preact/MobileMenuResponsive hamburger navigation menu
ItemBrowser@ever-works/ui/preact/ItemBrowserComposed search + filter + sort island

Standalone Components​

ThemeToggle and BackToTop work without data props:

---
import ThemeToggle from '@ever-works/ui/preact/ThemeToggle';
import BackToTop from '@ever-works/ui/preact/BackToTop';
---
<ThemeToggle client:load />
<BackToTop client:load showAfterPx={400} />

Dark Mode Configuration​

ThemeToggle sets data-theme="dark" on <html>. Configure Tailwind CSS v4:

@import "tailwindcss";
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

Add flash-prevention in <head>:

<script is:inline>
    (function() {
        var stored = localStorage.getItem('theme-preference');
        if (stored === 'dark' || (!stored && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
            document.documentElement.setAttribute('data-theme', 'dark');
        }
    })();
</script>

Data-Driven Components​

SearchInput, FilterBar, and SortSelect need callbacks. Compose them into a Preact island component. See apps/sample-basic/src/components/ItemBrowser.tsx for a complete reference.

Styling​

All components emit data-component and data-part attributes:

[data-component="search-input"] [data-part="input"] { /* style input */ }
[data-component="filter-bar"] [data-part="category-option"][data-selected] { /* active state */ }
[data-component="sort-select"] [data-part="select"] { /* style dropdown */ }
[data-component="back-to-top"] { /* position and style button */ }
[data-component="theme-toggle"] { /* style toggle button */ }

See apps/sample-basic/src/styles/global.css for complete styling reference.