Button
The
Button component allows users to make an action when the button is pressed.Basic usage
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.If the user doesn't have permissions to execute the task but can request it, the button will
instead trigger a request task dialog. See Permissions handling for details.
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.
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.
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.
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.Link
A Button can open a URL by setting the
href prop.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. | |
| fullWidth | boolean If true, the button will take up the full width of its container. | |
| sx | CSSObject CSS style overrides. | |
| leftAlign | boolean Whether to left align the button label. | false |
| 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<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[];
}
| AirplaneFunc
| {
fn: AirplaneFunc;
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 ( task="my_task") or an AirplaneFunc—the return value of airplane.task() (task={myTask}). 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. See [refetchTasks on a mutation](/views/task-caching#refetchtasks-on-a-mutation) for more information. | |
| 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. See [refetchTasks on a mutation](/views/task-caching#refetchtasks-on-a-mutation) for more information. |
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 |