Button
Basic usage
Loading view...
Task backed
A Button can be backed by an Airplane task by setting the
task prop. When it is clicked, it will call the task. The button
will show a loader until the task is complete and notify the user on error.The output of the task can be obtained using the
onSuccess callback or by using the result field
on the button's component state.Loading view...
Permission handling
The backend always verifies that the caller has the right permissions, but views also proactively
check request permissions. If the viewer is able to request the task but not execute it, a dialog is
shown when the button is clicked.
Runbook backed
A Button can be backed by an Airplane runbook as well, by setting the
runbook prop. When it is
clicked, it will call the runbook. Similar to tasks, the button will show a loader until the runbook
is complete, and notify the user on error.Note that unlike tasks, runbooks do not have outputs.
Loading view...
Presets
The
preset prop includes standard options for customizing the look and feel of a button.- primary: The primary page action. Usually there should only be one of these that represents the single most important thing a user can do.
- secondary: Secondary actions on a page. These are important, but not as important as the primary.
- tertiary: Supplemental actions that can be done on a page.
- danger: Actions that delete or do otherwise dangerous actions.
Loading view...
Variants and colors
Use
variant and color for more fine grained control than a preset. You can also override the
variant or color of a preset.Variants
- filled: Filled with a color.
- outline: White button outlined with a color.
- light: Filled with a light shade of a color.
- subtle: Creates a text button with no fill or outline.
Loading view...
Confirmation dialog
To show a confirmation dialog before the button's action (
onClick or task) is executed, set the
confirm prop.If the user clicks the
Cancel button, the action will not be executed.The dialog title, body, and buttons can be customized.
Disabling
A Button can be disabled by setting the
disabled prop.Loading view...
Link
A Button can open a URL by setting the
href prop.Loading view...
Component API
| Name | Description | Default |
|---|---|---|
| href | string | NavigateParams This can be either:
A string URL to navigate to when the button is clicked.
A task or view to navigate to in the form of { task: "task_slug" } or { view: "view_slug" }. You can also provide optional params. | |
| newTab | boolean Whether the href URL should open in a new tab. | true |
| id | string The ID referenced by the global component state | |
| preset | "primary" | "secondary" | "tertiary" | "danger" Built in button appearances that apply a set variant and color. The variant and/or color can be overriden by specifying a custom variant or color.
primary: The primary page action . Usually there should only be one of these that represents the single most important thing a user can do.
secondary: Secondary actions on a page. These are important, but not as important as the primary.
tertiary: Supplmental actions that can be done on a page.
danger: Actions that delete or do otherwise dangerous actions. | primary |
| variant | "filled" | "outline" | "light" | "subtle" Fine grained button appearance. Prefer using preset.
filled: Filled with a color
outline: White button outlined with a color.
light: Filled with a light shade of a color.
subtle: Creates a text button with no fill or outline. | |
| size | "xs" | "sm" | "md" | "lg" | "xl" Button size | |
| disabled | boolean Button disabled state | |
| color | "primary" | "secondary" | "dark" | "gray" | "red" | "pink" | "grape" | "violet" | "indigo" | "blue" | "cyan" | "teal" | "green" | "lime" | "yellow" | "orange" | "success" | "error" | `primary.${number}` | `secondary.${number}` | `dark.${number}` | `gray.${number}` | `red.${number}` | `pink.${number}` | `grape.${number}` | `violet.${number}` | `indigo.${number}` | `blue.${number}` | `cyan.${number}` | `teal.${number}` | `green.${number}` | `lime.${number}` | `yellow.${number}` | `orange.${number}` | `success.${number}` | `error.${number}` Button color | |
| children | Component Button label | |
| loading | boolean Renders a loading indicator when true | |
| radius | "xs" | "sm" | "md" | "lg" | "xl" Button border-radius | |
| compact | boolean Render a slimmer button with less padding | |
| type | "button" | "submit" | "reset" Button type attribute | |
| leftIcon | Component Icon to include on the left side of the button | |
| rightIcon | Component Icon to include on the right side of the button | |
| sx | CSSObject CSS style overrides | |
| width | number | "content" | "auto" | `${number}%` | `${number}/${number}` | { xs?: ColWidth; sm?: ColWidth; md?: ColWidth; lg?: ColWidth; xl?: ColWidth; } Width of the component. This component must be a direct child of a <Stack> for this prop to take effect.
If an integer is specified, signifies the width in a 12 item grid. 12 means that the component takes up
the entire row, 6 is half, 1 is 1/12.
If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 takes up half of the row.
If a percentage is specified, signifies the percentage share of the row. e.g. "50%" takes up half of the row.
content indicates that the component should take up as much space as its content.
auto indicates that the component should take any leftover space on the row.
To set width based on the screen size, use an object with a specific width for each breakpoint.
e.g. {xs: "100%", md: "50%"} sets the width on xs-md screens to 100% and md and larger screens to 50%. | content |
| offset | number | `${number}%` | `${number}/${number}` | { xs?: ColOffset; sm?: ColOffset; md?: ColOffset; lg?: ColOffset; xl?: ColOffset; } Creates a gap to the left of the component. Has the same units as width. This component must be a direct child of a <Stack> for this prop to take effect.
If an integer is specified, signifies the offset in a 12 item grid. 6 means the component is offset by half a row, 1 is 1/12 of a row.
If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 offsets a component by half of the row.
If a percentage is specified, signifies the percentage share of the row. e.g. "50%" offsets a component by half of the row.
To set offset based on the screen size, use an object with a specific offset for each breakpoint.
e.g. {xs: "50%", md: "0%"} sets the offset on xs-md screens to 50% and md and larger screens to 0%. | |
| onClick | MouseEventHandler<HTMLAnchorElement> | MouseEventHandler<HTMLButtonElement> Callback on click | |
| confirm | boolean
| {
title?: React.ReactNode | string;
cancelText?: string;
confirmText?: string;
body: React.ReactNode | string;
} Show a confirmation dialog before completing the button action.
If the user confirms, the dialog will close and the action will complete.
If the user cancels, the dialog will close and the action will not complete.
Set to true for a default confirmation dialog or customize the dialog title, body,
and buttons. | |
| task | string
| {
slug: string;
params?: Record<string, any>;
onSuccess?: (output?: TOutput) => void;
onFailure?: (output?: TOutput, error?: TError) => void;
refetchTasks?: RefetchQuery | RefetchQuery[];
} The task to execute when this button is pressed. If the task doesn't require any parameters or special options, you can just pass the task slug as a string. Otherwise, create an object with the given params, and set slug to the task slug. If the task requires parameters, these can be passed in via params. The onSuccess and onFailure callbacks will run on task success or failure. If you want to trigger a refetch of some other task(s) when this task completes, set the refetchTasks param. Each element can either be a task slug, or a { slug: string; params?: Record<string, any>; } object, indicating the tasks that should be refetched. | |
| runbook | string
| {
slug: string;
params?: Record<string, any>;
onSuccess?: () => void;
onFailure?: (error?: TError) => void;
refetchTasks?: RefetchQuery | RefetchQuery[];
} The runbook to execute when this button is pressed. If the runbook doesn't require any parameters or special options, you can just pass the runbook slug as a string. Otherwise, create an object with the given params, and set slug to the runbook slug. If the runbook requires parameters, these can be passed in via params. The onSuccess and onFailure callbacks will run on runbook success or failure. If you want to trigger a refetch of some other task(s) when this runbook completes, set the refetchTasks param. Each element can either be a task slug, or a { slug: string; params?: Record<string, any>; } object, indicating the tasks that should be refetched. |
State API
| Name | Description |
|---|---|
| result | {
output?: TOutput;
error?: {
message?: string;
type?: "AIRPLANE_INTERNAL" | "FAILED";
};
runID?: string;
} The result of the last task that was executed after clicking the button. Only applies for task backed buttons |