Components, controllers, and stores

Give renderable state, application behavior, and shared client state one clear owner each.

Begin with a plain component

A component that only transforms props into TSX should be a normal function. It is easier to read, test, and reuse because it owns no hidden behavior.

Create src/components/ProjectList.tsx

TSX

tsximport { Stack, Text } from "@tavojs/ui";

type ProjectSummary = { id: string; name: string };

export function ProjectList({ projects }: { projects: ProjectSummary[] }) {
  return (
    <Stack as="ul" gap="sm">
      {projects.map((project) => (
        <li>
          <Text>{project.name}</Text>
        </li>
      ))}
    </Stack>
  );
}

Add a local model for local interaction

When that mounted component needs renderable state, wrap it with createTavo and add a model. The filter below affects only this project list, so a global store would make ownership less clear.

Create src/components/ProjectFilter.tsx

TSX

tsximport { createTavo } from "@tavojs/core";
import { Button, Inline, Stack, Text } from "@tavojs/ui";

type Project = { id: string; name: string; active: boolean };
type ProjectFilterProps = { projects: Project[] };
type ProjectFilterState = { filter: "all" | "active" };

export const ProjectFilter = createTavo<ProjectFilterProps, ProjectFilterState>(
  {
    model: () => ({ filter: "all" }),
    view: ({ props, state, model }) => {
      const visibleProjects = props.projects.filter(
        (project) => state.filter === "all" || project.active,
      );

      return (
        <Stack gap="md">
          <Inline gap="sm">
            <Button onClick={() => model.patch({ filter: "all" })}>All</Button>
            <Button onClick={() => model.patch({ filter: "active" })}>
              Active
            </Button>
          </Inline>
          {visibleProjects.map((project) => (
            <Text>{project.name}</Text>
          ))}
        </Stack>
      );
    },
  },
);

Add a controller only for coordinated behavior

A Tavo.js component has a required view and optional model and controller. Add a controller when behavior needs lifecycle, cleanup, services, routing, subscriptions, or side effects. Keep small event handlers that only patch local model state in the view.

Share client state through named stores

A global store is appropriate when several mounted components or routes need the same client preference. Keep mutation methods beside the state so callers express intent rather than coordinating partial writes.

Create src/components/ActiveProjectButton.tsx

TSX

tsximport { createTavo, defineGlobalStore, TavoController } from "@tavojs/core";
import { Button } from "@tavojs/ui";

type FilterState = {
  status: "all" | "active";
  showActive(): void;
};

export const projectFilters = defineGlobalStore<FilterState>(
  "project-filters",
  (set) => ({
    status: "all",
    showActive: () => set({ status: "active" }),
  }),
);

class FilterController extends TavoController {
  showActive() {
    projectFilters.getState().showActive();
  }
}

export const ActiveProjectButton = createTavo({
  controller: FilterController,
  view: ({ controller }) => (
    <Button onClick={() => controller?.showActive()}>Show active</Button>
  ),
});

Make cleanup part of the behavior

Use onInit for subscriptions and initial model work, onMount or onLayout for DOM-dependent work, afterRender for post-commit behavior, and onPropsChange for explicit prop reactions. Return cleanup or register it with the controller so unmounting ends listeners and work.

Prefer controller helpers for events, store selection, resize, and intersection observation.
Subscribe to the smallest store value the component needs.
Keep request data in page or layout props instead of mirroring it into a process-wide store.

Checkpoint

Checkpoint

BASH

bashnpm run typecheck

Expected: TypeScript completes without errors. The route or component reproduces the behavior described in this guide.

If it does not work: Start with the first TypeScript error, confirm every shown file is in the documented location, and compare imports before changing runtime configuration.