# useMachine

`useMachine(definition, { input })` from `@pibbl/core/machines` creates one stable
actor per hook slot. It starts after a successful mounting render and stops on
unmount. An abandoned mounting render starts no tasks. Input and definition are
captured at initial mount; later input objects do not restart the actor.

Send events from handlers or owned work. Read `actor.snapshot.get()` in a component,
or select a field with `useComputed`. The initial render can observe `not-started`;
entry effects and tasks start only after the render succeeds.

```tsx
import { Text } from "@pibbl/core";
import { defineMachine, useMachine } from "@pibbl/core/machines";
const menu = defineMachine<undefined, { type: "TOGGLE" }>({
  initial: "closed",
  context: () => undefined,
  states: {
    closed: { on: { TOGGLE: "open" } },
    open: { on: { TOGGLE: "closed" } },
  },
});
function Menu() {
  const actor = useMachine(menu, { input: undefined });
  return (
    <Text onClick={() => actor.send({ type: "TOGGLE" })}>
      {actor.snapshot.get().value}
    </Text>
  );
}
```

See [machine authoring](/guides/state-machines/) and
[machine types](/reference/types/machines/).

Related types: [MachineDefinition](/reference/types/machines/#machinedefinition), [MachineActor](/reference/types/machines/#machineactor), [CreateMachineOptions](/reference/types/machines/#createmachineoptions).

## API details from source

<span id="api-useMachine"></span>

Creates one component-owned state-machine actor for a hook slot.

The actor starts only after its mounting render commits successfully and stops
when the component unmounts. Its input is captured on the initial mount;
changing an input object on a later render does not recreate or restart the
actor. Use machine events for application state changes.

```ts
useMachine: <Context, Event extends MachineEvent, Input, State extends string>(definition: MachineDefinition<Context, Event, Input, State>, options: { readonly input: Input; }) => MachineActor<Context, Event, Input, State>
```

Related API: [useMachine](/reference/hooks/use-machine/), [MachineEvent](/reference/types/machines/#machineevent), [MachineDefinition](/reference/types/machines/#machinedefinition), [MachineActor](/reference/types/machines/#machineactor).

### Type parameters

- **`Context`** — Immutable machine context carried by each snapshot.

- **`Event`** — Events accepted by the machine actor.

- **`Input`** — Immutable input captured when this hook slot mounts.

### Parameters

- **`definition`** — Immutable machine behavior shared by all actor instances.

- **`options`** — Input used to initialize this mounted actor.

### Returns

A stable actor with a readonly reactive snapshot.

### Examples

```tsx
const actor = useMachine(menuMachine, { input: { initialOpen: false } });
const open = () => actor.send({ type: 'OPEN' });
return <Text>{actor.snapshot.get().value}</Text>;
```

### See also

[createMachine](/reference/functions/machines/)

[MachineActor](/reference/types/machines/#machineactor)

[View source — packages/core/src/features/machines/hook.ts:52](/source/packages/core/src/features/machines/hook-ts/#L52)

## Implementation guidance for agents

Read the [Authoring, signals, and lifecycle companion](/agents/topics/lifecycle/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Cancelable machine tasks](/minimal-examples/machines/tasks/): Run a state-owned task, observe completion, and release actors and listeners. [Plain source](/minimal/machines/tasks.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.