Function useMachine

Uses a state machine with the constructor.

Each time the state machine transitions to a new state, React.setState is called internally, triggering a re-render of the component.

The state machine constructor is executed only once per hook. It is idempotent unless it depends on external mutable values within the constructor.

Example

import { useMachine, createMachine } from "use-machine-ts"

function machine() {
  return createMachine({
    // definition
    {
      initial: "inactive",
      states: {
        inactive: {
          on: { TOGGLE: "active" },
          effect: "onInactive",
        },
        active: {
          on: { TOGGLE: "inactive" },
          effect: "onActive",
        },
      },
    },
    // configuration
    {
      effects: {
        onActive: () => {
          console.log("Just activated!")
        },
        onInactive: () => {
          console.log("Just deactivated!")
        },
      },
    },
  })
}

function ToggleButton(props: {}) {
  const [state, send] = useMachine(machine)

  return (
    <button onClick={() => send("TOGGLE")} type="button">
      Now: {state.value}
    </button>
  )
}
Copy

Uses a state machine with the constructor and props.

Each time the state machine transitions to a new state, React.setState is called internally, triggering a re-render of the component.

The state machine constructor is executed only once per hook. It is idempotent unless it depends on external mutable values within the constructor.

The props passed to the state machine constructor are different from the props of a React component; they are represented as a function. When this function is executed, it returns a reference to the props passed to the hook. This mechanism is implemented using React.useRef, ensuring that it always returns a reference to the latest props.

Example

import { useMachine, createMachine } from "use-machine-ts"

function machine(props: () => { onToggle }) {
  return createMachine({
    // definition
    {
      initial: "inactive",
      states: {
        inactive: {
          on: { TOGGLE: "active" },
          effect: "onInactive",
        },
        active: {
          on: { TOGGLE: "inactive" },
          effect: "onActive",
        },
      },
    },
    // configuration
    {
      effects: {
        onActive: () => {
          const { onToggle } = props()
          onToggle("active")
        },
        onInactive: () => {
          const { onToggle } = props()
          onToggle("inactive")
        },
      },
    },
  })
}

function ToggleButton(props: { onToggle: (value: "active" | "inactive") => void }) {
  const [state, send] = useMachine(machine, props)

  return (
    <button onClick={() => send("TOGGLE")} type="button">
      Now: {state.value}
    </button>
  )
}
Copy

Uses a state machine with the pre-created instance.

Each time the state machine transitions to a new state, React.setState is called internally, triggering a re-render of the component.

We can use a pre-created state machine instance with the hook. It is idempotent unless it depends on external mutable values within the effect. In most cases, it is better to define the state machine using the constructor instead.

To enable tree shaking, you can indicate to the bundler that this function has no side effects by using the @__PURE__ or #__PURE__ annotation as needed.

Example

import { useMachine, createMachine } from "use-machine-ts"

const machine = createMachine({
  // definition
  {
    initial: "inactive",
    states: {
      inactive: {
        on: { TOGGLE: "active" },
        effect: "onInactive",
      },
      active: {
        on: { TOGGLE: "inactive" },
        effect: "onActive",
      },
    },
  },
  // configuration
  {
    effects: {
      onActive: () => {
        console.log("Just activated!")
      },
      onInactive: () => {
        console.log("Just deactivated!")
      },
    },
  },
})

function ToggleButton(props: {}) {
  const [state, send] = useMachine(machine)

  return (
    <button onClick={() => send("TOGGLE")} type="button">
      Now: {state.value}
    </button>
  )
}
Copy

Define a state machine and uses it.

Each time the state machine transitions to a new state, React.setState is called internally, triggering a re-render of the component.

This approach is useful when you want to quickly define and use a simple state machine on the spot. For complex definitions, it is usually better to write them in a separate file and import it. However, if the definition does not impair readability, keeping it within the component can actually make it more readable.

Example

import { useMachine } from "use-machine-ts"

function ToggleButton(props: {}) {
  const [state, send] = useMachine(
    // definition
    {
      initial: "inactive",
      states: {
        inactive: {
          on: { TOGGLE: "active" },
        },
        active: {
          on: { TOGGLE: "inactive" },
        },
      },
    },
  )

  return (
    <button onClick={() => send("TOGGLE")} type="button">
      Now: {state.value}
    </button>
  )
}
Copy

Define a state machine and uses it.

Each time the state machine transitions to a new state, React.setState is called internally, triggering a re-render of the component.

This approach is useful when you want to quickly define and use a simple state machine on the spot. For complex definitions, it is usually better to write them in a separate file and import it. However, if the definition does not impair readability, keeping it within the component can actually make it more readable.

Example

import { useMachine } from "use-machine-ts"

function ToggleButton(props: {}) {
  const [state, send] = useMachine(
    // definition
    {
      initial: "inactive",
      states: {
        inactive: {
          on: { TOGGLE: "active" },
          effect: "onInactive",
        },
        active: {
          on: { TOGGLE: "inactive" },
          effect: "onActive",
        },
      },
    },
    // configuration
    {
      effects: {
        onActive: () => {
          console.log("Just activated!")
        },
        onInactive: () => {
          console.log("Just deactivated!")
        },
      },
    },
  )

  return (
    <button onClick={() => send("TOGGLE")} type="button">
      Now: {state.value}
    </button>
  )
}
Copy