Calling tasks with React hooks
- When using a component that is not task backed (e.g. a
Dialog
orTypography
). - When using a custom, non-Airplane component.
- When you want to do something more custom with a task output than just populate a component. e.g. show different components depending on the output of a task.
useTaskQuery
and
useTaskMutation
hooks. When you
use these hooks, you are in charge of populating components with data as well as handling loading
and error states.Queries
useTaskQuery
should be used for tasks that query for data. It has intelligent behavior for queries
like caching and automatically refetching to keep the task output fresh.list_cats
task returns a list of cats filtered by name. Every time
you type in the input, the task is re-executed with the new name filter and the new, filtered output
is displayed. The useTaskQuery
hook is smart enough to re-execute the task whenever the task slug
or the parameters are changed.tsxCopied1const [filter, setFilter] = useState("");2const { output, loading, error } = useTaskQuery({ slug: "list_cats", params: { filter } });3if (loading) return <Loader />;4if (error) return <Callout variant="error">{error.message}</Callout>;5const items = output?.map((cat) => ({ term: cat.name, description: cat.breed }));6return (7<Stack spacing="lg">8<TextInput9label="Cat name filter"10onChange={(e) => {11setFilter(e.target.value);12}}13/>14<Card>15{items.length > 0 ? (16<DescriptionList height="48u" style={{ overflow: "auto" }} items={items} />17) : (18<Text>No cats π</Text>19)}20</Card>21</Stack>22);
Manual refetch
list_cats
might
be an expensive task that you only execute when a button is clicked. In these cases, you can set the
enabled
option to false
to disable the initial execution and then call the refetch
function
when the button is clicked.refetch
does not take arguments. refetch
executes the task with the same parameters that are
passed to the useTaskQuery
hook.tsxCopied1const [filter, setFilter] = useState<string>("");2const { output, loading, error, refetch } = useTaskQuery({3slug: "list_cats",4params: { filter },5enabled: false,6});7if (loading) return <Loader />;8if (error) return <Callout variant="error">{error.message}</Callout>;9const items = output?.map((cat) => ({ term: cat.name, description: cat.breed }));10return (11<Stack spacing="lg">12<Stack direction="row" align="end">13<TextInput14label="Cat name filter"15onChange={(e) => {16setFilter(e.target.value);17}}18grow19/>20<Button21onClick={() => {22refetch();23}}24>25Search26</Button>27</Stack>28<Card>29{items.length > 0 ? (30<DescriptionList height="48u" style={{ overflow: "auto" }} items={items} />31) : (32<Text>No cats π</Text>33)}34</Card>35</Stack>36);
Mutations
useTaskMutation
should be used for tasks that create, update, or delete data.tsxCopied1const { id, value } = useComponentState();2const { mutate } = useTaskMutation({3slug: "pet_cat",4params: { num_times: 1, name: value },5onSuccess: () => {6showNotification({ message: "Petted cat", type: "success" });7},8});9return (10<Stack>11<Form12onSubmit={() => {13mutate();14}}15>16<Select id={id} required label="Cat to pet" data={["Bootz", "Hazel", "Baosky"]} />17</Form>18</Stack>19);
useRunbookMutation
works similarly to useTaskMutation, but is used for executing runbooks instead
of tasks.useTaskQuery("my_task")
or an AirplaneFunc
βthe return value of airplane.task()
:
useTaskMutation(myTask)
.API Reference
useTaskQuery
Options
The task to execute. This is the return value of
airplane.task()
.Example:
useTaskQuery({ fn: MyTask })
The slug of the task to execute.
The params of the task to execute.
false
, the task will not be executed automatically. To execute a disabled task, use the returnedrefetch
function.refetchInterval
milliseconds.Callback on successful task execution.
Callback on failed task execution.
true
, the task will be executed on mount.true
, the task will be executed on window focus.true
, the task will be executed on reconnect.Returns
The output of the last executed task.
true
when the task is currently executingThe error message if the task failed to execute. The type indicates whether the error is due to Airplane failing to execute the task, due to the task itself failing, or due to a client error.
enabled
option.The ID of the run.
useTaskMutation
Options
The task to execute. This is the return value of
airplane.task()
.Example:
useTaskMutation({ fn: MyTask })
The slug of the task to execute.
The params of the task to execute.
RefetchQuery
is either a task slug, an AirplaneFunc
, or an object of{ slug?: string; fn: AirplaneFunc?; params?: object }
representing a task. If set, the provided tasks will be refetched on success. This can be useful if you expect the task mutation to invalidate data. See refetchTasks on a mutaiton for more information.Callback on successful task execution.
Callback on failed task execution.
Returns
The output of the last executed task.
true
when the task is currently executingThe error message if the task failed to execute. The type indicates whether the error is due to Airplane failing to execute the task, due to the task itself failing, or due to a client error.
The ID of the run.
A function that executes the task.
useRunbookMutation
Options
The slug of the runbook to execute.
The params of the runbook to execute.
RefetchQuery
is either a task slug, an AirplaneFunc
, or an object of{ slug?: string; fn: AirplaneFunc?; params?: object }
representing a task. If set, the provided tasks will be refetched on success. This can be useful if you expect the runbook mutation to invalidate data. See refetchTasks on a mutaiton for more information.Callback on successful runbook execution.
Callback on failed runbook execution.
Returns
true
when the runbook is currently executingThe error message if the runbook failed to execute. The type indicates whether the error is due to Airplane failing to execute the runbook, due to the runbook itself failing, or due to a client error.
The ID of the session.
A function that executes the runbook.