Ship Preact features faster with production-ready hooks

# Hooks — integration reference

A Preact-first hook library inspired by ahooks — state, lifecycle, browser, and async helpers with zero runtime dependencies beyond Preact.

Package: @kamod-ch/hooks

## Choose an approach

Reach for a hook when a component needs reusable behavior: a boolean state, a bounded counter or a browser preference. Keep the visual control in Kamod UI and the behavior in the hook.

### One component's interaction

Start with useToggle or useCounter and let the component own the state.

Avoid a shared store just to open one panel or change one quantity.

### A browser preference

Use useLocalStorageState when a value should survive reloads.

Validate stored data and choose a safe default; persistence is not input validation.

### Browser or asynchronous behavior

Pick the dedicated hook after reviewing its lifecycle and options.

Check cleanup and stale results when the component unmounts or its inputs change.

## Installation

Install @kamod-ch/hooks with Preact as a peer dependency when using the package outside the Kamod UI monorepo.

```bash
pnpm add @kamod-ch/hooks preact
```

## Starting example

```tsx
import { useToggle, useCounter, useLocalStorageState } from "@kamod-ch/hooks";

export function useExampleState() {
  const [on, { toggle }] = useToggle(false);
  const [count, { inc }] = useCounter(0);
  const [theme, setTheme] = useLocalStorageState("theme", { defaultValue: "dark" });
  return { on, toggle, count, inc, theme, setTheme };
}
```

### Separate the value from its actions

The first item describes what to render. The second contains operations that change it. Call the hook at the top level of a component or custom hook; call toggle from the event handler, not while rendering.

```tsx
const [on, { toggle }] = useToggle(false);
```

### Make the limits part of the behavior

Put the bounds in the hook and reflect them in the controls. A disabled button explains the boundary visually, while the hook keeps programmatic changes inside the same range.

```tsx
const [count, { inc, dec, reset }] = useCounter(1, { min: 1, max: 5 });
```

### Choose a default for an empty browser

The second argument is an options object. A default is used when no saved value exists; it is not a validation rule for old data. Check stored values before treating them as a restricted theme name.

```tsx
const [theme, setTheme] = useLocalStorageState("theme", { defaultValue: "dark" });
```

## Connect a bounded quantity control

This example keeps behavior local and uses the same Kamod buttons as the rest of the interface. The disabled states explain the limits, and reset returns to the starting quantity. Render it twice to see that each instance owns its own count.

File: src/components/Quantity.tsx

```tsx
import { useCounter } from "@kamod-ch/hooks";
import { Button } from "@kamod-ch/ui";

export function Quantity() {
  const [count, { inc, dec, reset }] = useCounter(1, { min: 1, max: 5 });
  return (
    <div role="group" aria-label="Quantity" class="flex flex-wrap items-center gap-2">
      <Button variant="outline" disabled={count === 1} onClick={() => dec()}>Remove one</Button>
      <output aria-live="polite">{count}</output>
      <Button variant="outline" disabled={count === 5} onClick={() => inc()}>Add one</Button>
      <Button variant="ghost" onClick={reset}>Reset</Button>
    </div>
  );
}
```

Try the minimum, maximum and reset paths with a keyboard. When this becomes a cart control, send the intended quantity through your application boundary and handle server rejection separately; a local count is not proof of available stock.

## Ownership and environment

Start with the smallest owner that needs the behavior. Move a hook into a custom hook when several components need the same logic, not simply because a file is long. Sharing the function does not share its state: separate calls still represent separate instances. Lift ownership only when the product requires synchronized values.

Browser hooks and server rendering have different timing. Keep direct access to window, document and storage out of server render paths. Prefer a stable initial render and apply browser-only information after mount. For asynchronous interactions, decide what the user sees while a request is pending and when a later request replaces it.

A reusable interaction should preserve its behavior when the surrounding markup changes. Keep hook ownership stable while adjusting buttons, labels and layout.

## Troubleshooting

### The value resets unexpectedly

Check whether a changing key or a conditional parent unmounts the component. Local state belongs to that mounted instance; moving the visual control can change its lifetime.

### The saved preference has an unexpected type

Inspect old storage values and your serializer. TypeScript describes current code, not historical browser data. Test fresh storage and an older value before deciding on a migration.

### An interaction repeats or finishes late

Look for listeners, timers or requests created outside the hook's lifecycle. Verify cleanup when navigating away and rapid repeated input; do not hide the issue by suppressing all errors.

## Resources

- [Documentation](https://kamod-ch.github.io/kamod-hooks/)
- [Source](https://github.com/kamod-ch/kamod-hooks)
- [npm](https://www.npmjs.com/package/@kamod-ch/hooks)

## Attribution

Kamod Hooks is inspired by ahooks and adapts those patterns for Preact. Consult the package's LICENSE and NOTICE when redistributing source; compatibility and behavior should be checked against Kamod's own documentation.

[ahooks by Alibaba](https://github.com/alibaba/hooks)