DocsBlog

  • 1.1.2

  • light

    dark

    system

    Switch mode

  • Cerberus

    Acheron

    Elysium

Get Started
Components
Data Grid
Signals
Styling
Theming

Get Started

OverviewReactivityData FetchingStores

Primitives

createSignalcreateQuerycreateMutationcreateComputedcreateEffectcreateStoreContextbatch

Hooks

useQueryuseMutationuseReaduseSignal

Components

ReactiveText

On this page

  • Edit this page on Github

Using Mutations

Learn how to use defined mutations in React.

  • source
import { useMutation } from '@cerberus/signals'

Usage

useMudation allows you call a defined mutation (via createMutation) to trigger and action for usage within your React component.

Mutations's have built in support for Suspense and Error Boundaries with no extra effort.

Using Mutations

To use a mutation call the mutate method from the return Object.

Data

The data property is a mirrored store of the query associated with the mutation.

Status

The status property is the state associated with the mutation when triggered.

API

useMutation accepts the following options:

ParamsRequiredDescription
MutationTupletrueThe result of the mutation defined.

Return

useMutation returns and Object with the following options:

PropertyTypeDescription
mutate(variables: V) => Promise<T>A function that calls the defined mutation Promise.
dataT | undefinedThe cached state of the query associated with it.
errorunknown | undefinedThe error thrown from the mutation.
statusMutationStatusThe Promise-based status state of the mutation.
Copy
'use client'

import { Box, Stack } from '@/styled-system/jsx'
import { Button } from '@cerberus/react'
import { createMutation, createQuery, useMutation, useQuery } from '@cerberus/signals'
import { Suspense } from 'react'

// Fake DB

type User = {
  id: string
  name: string
}

let dbUser: User = { id: '', name: '' }

// Data fetching

const query = createQuery(
  () => 'init',
  async () => dbUser,
)

const mutation = createMutation(
  async (newId: User['id']) => {
    dbUser = { id: newId, name: `User ${newId}` }
    return dbUser
  },
  {
    invalidate: () => [query.key],
  },
)

// UI

function UserInfo() {
  const data = useQuery(query)
  return <pre>{JSON.stringify(data, null, 2)}</pre>
}

export function MutationDemo() {
  const { mutate } = useMutation(mutation)

  return (
    <Stack direction="column" justify="space-between" w="3/4">
      <Suspense fallback={<Box aria-busy h="200px" w="full" />}>
        <UserInfo />
      </Suspense>

      <Button onClick={() => mutate(crypto.randomUUID())}>Change User</Button>
    </Stack>
  )
}
Copy
'use client'

import { Box, Stack } from '@/styled-system/jsx'
import { Button, Text } from '@cerberus/react'
import { createMutation, createQuery, useMutation, useQuery } from '@cerberus/signals'
import { Suspense } from 'react'

// Fake DB

type User = {
  id: string
  name: string
}

let dbUser2: User = { id: '', name: '' }

// Data fetching

const query2 = createQuery(
  () => 'init2',
  async () => dbUser2,
)

const mutation = createMutation(
  async (newId: User['id']) => {
    dbUser2 = { id: newId, name: `User ${newId}` }
    return dbUser2
  },
  {
    invalidate: () => [query2.key],
  },
)

// UI

function UserInfo() {
  const data = useQuery(query2)
  return <pre>{JSON.stringify(data, null, 2)}</pre>
}

export function DataDemo() {
  const { mutate, data } = useMutation(mutation)

  return (
    <Stack direction="column" justify="space-between" w="3/4">
      <Suspense fallback={<Box aria-busy h="200px" w="full" />}>
        <UserInfo />
      </Suspense>

      <Stack direction="column">
        <Text as="small">Data:</Text>
        <pre>{JSON.stringify(data, null, 2)}</pre>
      </Stack>

      <Button onClick={() => mutate(crypto.randomUUID())}>Change User</Button>
    </Stack>
  )
}
Copy
'use client'

import { Box, Stack } from '@/styled-system/jsx'
import { Button, Text } from '@cerberus/react'
import { createMutation, createQuery, useMutation, useQuery } from '@cerberus/signals'
import { Suspense } from 'react'

// Fake DB

type User = {
  id: string
  name: string
}

let dbUser2: User = { id: '', name: '' }

// Data fetching

const query2 = createQuery(
  () => 'init2',
  async () => dbUser2,
)

const mutation = createMutation(
  async (newId: User['id']) => {
    dbUser2 = { id: newId, name: `User ${newId}` }
    return dbUser2
  },
  {
    invalidate: () => [query2.key],
  },
)

// UI

function UserInfo() {
  const data = useQuery(query2)
  return <pre>{JSON.stringify(data, null, 2)}</pre>
}

export function StatusDemo() {
  const { mutate, status } = useMutation(mutation)

  return (
    <Stack direction="column" justify="space-between" w="3/4">
      <Suspense fallback={<Box aria-busy h="200px" w="full" />}>
        <UserInfo />
      </Suspense>

      <Stack>
        <Text as="small">Status :</Text>
        <pre>{JSON.stringify(status, null, 2)}</pre>
      </Stack>

      <Button onClick={() => mutate(crypto.randomUUID())}>Change User</Button>
    </Stack>
  )
}
Data:
Status :
"idle"
{
  "id": "",
  "name": ""
}
{
  "id": "",
  "name": ""
}
{
  "id": "",
  "name": ""
}