Packages libraryChoose · Integrate · Verify

Focused packages for the rest of your Preact app

Explore 5 standalone Kamod packages for behavior, state, icons and localization. Add the capability your project needs without replacing the rest of your stack. Each entry leads to installation steps, usage guidance and the package’s dedicated documentation, with Preact as the common UI foundation.

Choose one package, try one example, then connect it to your app. Use the selection guide to separate local behavior from shared state and persistence. Each package guide includes setup, working patterns and links to its own source and API documentation.

In this guide 7 sections

Find the capability your app needs

These libraries are independent companions to @kamod-ch/ui. Choose the responsibility you need below; each guide takes you from installation to practical examples. You do not need to install the whole collection.

Choose the smallest useful package set

Start with a capability, not a dependency list. The packages can be used independently. A local boolean does not require a store, and an icon does not require a persistence layer. Identify the problem your application has today, then follow that package’s installation and usage documentation.

The directory above separates responsibilities. Keep those boundaries clear when you combine libraries: a hook manages nearby behavior, a store coordinates domain changes, and persistence decides what survives beyond the current session.

Keep one owner for each responsibility

Is the behavior local?: Start with useState. Reach for Hooks when the same behavior repeats across components.
Does it need to survive a reload?: Explore Signals. Define the storage key, initial value and reset behavior together.
Do several actions change one model?: Explore State. Make transitions explicit and keep derived values out of storage.

These approaches can coexist, but do not mirror the same value in several places without a clear synchronization contract. One source of truth is easier to test and restore. Keep derived values derived, and store only the minimum data required to reconstruct the interface.

Try one capability at a time

These examples build on an existing Preact and Kamod UI setup. Install the selected package and its required peers before copying the source. Use the paths as a suggestion; keep your app’s own module organization and public import conventions.

The live hook example is deliberately local. It lets you inspect state and keyboard behavior without changing storage or contacting a service. The persistence example is copyable source with a client-rendering assumption, not a setting for this docs site.

Pair reusable behavior with a semantic control

useToggle keeps the state transition small. A core Button still provides the control, while aria-expanded and aria-controls explain which content it reveals. The live example stays local and resets on reload.

src/components/DetailsToggle.tsx

import { useToggle } from "@kamod-ch/hooks";
import { Button } from "@kamod-ch/ui";

export function DetailsToggle() {
  const [open, { toggle }] = useToggle(false);
  return (
    <div class="space-y-3">
      <Button type="button" variant="outline" onClick={toggle}
        aria-expanded={open} aria-controls="package-details">
        {open ? "Hide details" : "Show details"}
      </Button>
      <p id="package-details" hidden={!open}>
        A hook owns behavior; a component presents the interaction.
      </p>
    </div>
  );
}

Check the result

Try Enter and Space on the button. Use unique IDs if this example appears more than once. A single boolean may also be handled with Preact’s useState; choose the abstraction that helps your project.

Integrate with the project you already have

Check versions, peers and entry points

Inspect package.json and the lockfile before adding dependencies. Reuse your existing package manager, check peer requirements and install only what is missing. In a workspace, add the package to the app that imports it rather than assuming the repository root supplies it everywhere.

For a pnpm project, the following commands help inspect an existing dependency and add the hooks package if needed. Other package managers have equivalent commands. Follow the package installation guide for its full setup and verify that your existing Preact version satisfies the requirement.

Terminal

# Inspect the existing dependency before adding another copy.
pnpm why @kamod-ch/hooks

# Add only if the application does not already declare it.
pnpm add @kamod-ch/hooks

Keep imports explicit and documented

Use published entry points, such as @kamod-ch/icons/lucide, instead of importing a file from a package’s internal source tree. Internal layouts can change independently of the public API. Copy an icon’s exact exported name from its catalog and verify the current hook signature instead of assuming it matches a similarly named React library.

Named imports make intent easy to review. Avoid constructing a registry that eagerly imports every icon just to render one name. Inspect your production output when bundle size matters; an import style alone is not a measurement.

Hooks, state and translation logic do not replace your global UI stylesheet. Keep the CSS setup for Kamod components in place, and use semantic tokens when styling UI built around a package.

Plan for reloads, requests and cleanup

Make persistence an explicit decision

Persist a preference because the user expects it to survive, not because every state value can be saved. Choose a storage driver that fits the lifetime: a local browser preference, a session value and server-readable cookie state have different tradeoffs. Namespace keys, define defaults and decide how reset works before shipping.

Stored values may be absent, malformed or written by an older version. Validate their shape and plan a migration when it changes. Treat browser storage as untrusted input and keep sensitive account data in the appropriate application service. Test with storage blocked as well as with a fresh profile.

Keep the first render consistent

Browser APIs such as window and localStorage are unavailable during server rendering. Follow each package’s server guidance and initialize browser-only work at the appropriate client boundary. A fallback that prevents a server crash is only part of the job; the initial HTML and hydrated state also need to agree.

Keep user-specific stores and locale instances scoped to a request rather than a mutable module singleton. For @kamod-ch/i18n, align the server and client locale, make the required messages available for the first render, and update langand direction when the locale changes. Include translated labels and errors, not just visible headings.

Give long-lived work an owner

Use a hook’s built-in lifecycle behavior when it fits. When you add your own listeners, observers, timers or subscriptions, remove them when their owner unmounts or their inputs change. Cancel obsolete requests where supported and prevent stale responses from replacing newer data.

Verify navigation away as well as navigation in. Repeatedly mount and unmount the feature, switch routes during a pending operation and confirm callbacks do not accumulate. Use component-scoped helpers when they match the lifetime instead of creating a new global controller during every render.

Verify the integration, not just the import

A successful import confirms that a module resolves. It does not confirm that state, persistence or rendering behaves correctly in your app. Check the whole lifecycle before you consider the integration complete.

Dependencies. Confirm the owning workspace declares the package and its peers. Review the lockfile diff and verify that no unintended runtime or duplicate framework was introduced.
Behavior. Test the state transitions your screen relies on, including retry, reset and cancellation. Keep accessible labels and control state synchronized.
Environment. Try a direct route load, a refresh and client navigation. For SSR, check hydration; for persistence, check missing and older stored values.
Lifecycle. Leave the screen while work is pending. Confirm listeners, timers and observers are cleaned up, and that returning does not double the callbacks.
Production. Run the project’s typecheck, relevant tests and build. Inspect the generated bundle when size matters and verify the built app with its actual routes, assets and deployment base path.

When reporting an issue, include the package version, the relevant import, runtime or browser and a small reproduction. Each package’s documentation links to its own source and issue tracker. Use the component library to turn the behavior into a consistent, accessible interface.

Connect the behavior to your interface

The package owns a capability; your interface gives it context. Pair behavior with the component library, or explore complete blocks to see how navigation, forms and content fit together. Keep these shared foundations in place as you integrate.

Connect your styles

When your example uses @kamod-ch/ui, keep its global stylesheet and Tailwind source detection in place. Behavior packages do not replace the interface’s CSS setup.

CSS setup

Customize the theme

Use shared semantic tokens for colors, surfaces and focus indicators. Check the same interaction in light and dark before adding local overrides.

Theming & Tailwind

Explore the icon library

Choose one icon family for related actions and let it inherit currentColor. Give icon-only controls an accessible name that describes the action.

Icons guide

Work with the source

Each package guide links to its own repository, API and package listing. Compare the version in package.json with the documentation before adapting an example. For a bug report, include that version, the import path and the smallest reproduction that shows the behavior.

Read the UI implementation for component behavior, or browse Kamod’s repositories for the package that owns the issue. Keep fixes with the responsibility they belong to.