GitHub icon

Hierarchy

Strict order of buttons is not necessary. Visual hierarchy between Buttons is the important goal.

Primary Actions

As a rule, only a single primary action should be present at a time to draw the user through a flow.

Destructive primary actions use a negative color. Clicking this should trigger a confirmation (usually as a Dialog) before proceeding with the action.

Secondary Actions

When multiple actions surface information or start a workflow, the secondary variant can be used. It also pairs well with a primary action.

A negative equivalent also exists. It is used when a destructive action is less prominent, usually paired with other buttons.

Tertiary Actions

For less pronounced, common actions throughout a page.

An alternative tertiary style also exists. It's used when solid gray is unable to visually work, such as on non-white backgrounds, or pairing with a secondary action.

Subtle Actions

On data-heavy UIs, the subtle style can be used in large quantities without adding heavy visuals.

Text-based Subtle Actions

When the button is Text, the blue variant is preferred over gray to preserve the Button's signifier to the user.

Icon-based Subtle Actions

For Icons, the gray variant is preferred if the icon is understandable to end users.

Pairing Guidelines

See the Button Group component guidelines on applying button hierarchy to multiple buttons.

Alignment

Left Aligned

Left-aligned buttons are recommended for single page forms and focused tasks. The buttons are ordered from left to right by importance.

<Form>
	<Headline el="div" className="m-b-4">Add Contact</Headline>
	<Form.Group widths="equal">
		<Form.Input label="First Name" placeholder="Leia" />
		<Form.Input label="Last Name" placeholder="Organa" />
	</Form.Group>
	<Form.Select label="Home Planet" placeholder="Choose Planet" options={[
		{key:1, value: 1, text: 'Alderaan'},
		{key:2, value: 2, text: 'Bespin'},
		{key:3, value: 3, text: 'Coruscant'},
		{key:4, value: 4, text: 'Dagobah'},
		{key:5, value: 5, text: 'Hoth'},
		{key:6, value: 6, text: 'Kashyyyk'},
		{key:7, value: 7, text: 'Naboo',},
		{key:8, value: 8, text: 'Tatooine'},
		{key:9, value: 9, text: 'Yavin'},
	]} />
	<Form.Group>
		<Form.Button primary>Save Contact</Form.Button>
		<Form.Button>Cancel</Form.Button>
	</Form.Group>
</Form>

Right Aligned

Buttons in page headers and footers prompt a user to move through a sequence of screens are right aligned to visually support navigation. The buttons are ordered from right to left by importance.

Within Overlays, like Modals, actions are right-aligned as well to encourage forward progress through a workflow.

Centered

Centered buttons are used when the content is shown in a small, isolated view. These should be used sparingly and are most commonly within overlay-based components such as Modals.

Variations

Colors

There are three color variations for buttons. Blues and reds tend to be more prominent in a neutral-dominant UI, while grays allow for deemphasized actions.

<Stack spacing={3} justifyContent="space-around" className="w-100" wrap="wrap">
	<Stack direction="column" spacing={3} className="p-b-2">
		<Button full primary>Primary Solid</Button>
		<Button full outline primary>Secondary Outline</Button>
		<Button full fill='subtle' primary>Subtle Blue</Button>
	</Stack>
	<Stack direction="column" spacing={3} className="p-b-2">
		<Button full>Tertiary Solid</Button>
		<Button full outline>Tertiary Outline</Button>
		<Button full fill='subtle'>Subtle Gray</Button>
	</Stack>
	<Stack direction="column" spacing={3} className="p-b-2">
		<Button full negative>Negative Solid</Button>
		<Button full outline negative>Secondary Negative</Button>
		<Button full fill='subtle' negative>Subtle Negative</Button>
	</Stack>
</Stack>

Fills

There are three fills a button can have. A solid fill is useful for bold and important actions. An outline fill can be used for secondary actions and looks good next to a solid button and stand out on colored backgrounds. A subtle fill is useful for actions that don't need to call a lot of attention to.

Disabled

We have two separate ways of disabling buttons. A disabled attribute will prevent clicks and change the button to a grey style. An inactive attribute will prevent clicks but keeps the button looking the same. This is useful for preventing stray clicks while an API call is running or showing an outlined-to-active state change.

Sizes

We support three sizes of buttons that can be set using the size prop. Small buttons are useful for secondary or ancillary actions. Large buttons are great for important call-to-actions and helping unstick a user in a setup flow.

Widths

The default width of buttons has a consistent amount of padding between the text and the ends of the button. This can be overridden with the width property, either setting it to a specific size or making the button full width. Specific sized buttons should only be used when buttons are next to each other or in a column and have variable text lengths. Keeping them the same width will make the buttons feel intentional. Setting a width for every button is not recommended.

with Icon

Buttons can have an icon to the left or right of the action label.

Button Icons

When pairing an Icon and an action, an Icon-only Button is used to control the interaction. To add clarity to the action, Button Icons should be paired with Tooltips.

<ButtonGroup>
	<Tooltip el="div" text="Add New Widget" portal><Button iconName="add"/></Tooltip>
	<Tooltip el="div" text="Edit Invoice" portal><Button iconName="edit"/></Tooltip>
	<Tooltip el="div" text="Check Availability" direction="b" portal><Button iconName="event" /></Tooltip>
	<Tooltip el="div" text="More Actions" direction="t" portal><Button iconName="more_vert" /></Tooltip>
</ButtonGroup>

<State initial={5}>
	{([state, setState]) => (
		<Form>
			<Stack spacing="1">
				<Tooltip el="div" text="Remove Widgets">
					<Button onClick={() => setState(state - 1)} iconName="remove" />
				</Tooltip>
				<Input style={{width: '50px'}} value={state} />
				<Tooltip el="div" text="Add More Widgets" direction="t">
					<Button onClick={() => setState(state + 1)} iconName="add" primary />
				</Tooltip>
			</Stack>
			<Stack spacing="1" className="m-t-3">
				<Tooltip el="div" text="Remove Widgets">
					<Button onClick={() => setState(state - 1)} iconName="remove" small />
				</Tooltip>
				<Input small style={{width: '50px'}} value={state} />
				<Tooltip el="div" text="Add More Widgets" direction="t">
					<Button onClick={() => setState(state + 1)} iconName="add" primary small />
				</Tooltip>
			</Stack>
		</Form>
	)}
</State>

<State initial={1}>
	{([state, setState]) => {
		const options = [
			{key: 1, value: 1, text: 'Australia'},
			{key: 2, value: 2, text: 'Argentina'},
			{key: 3, value: 3, text: 'Bolivia'},
		];
		return (
			<Form>
				<Stack spacing="1">
					<Select options={options} value={state} onChange={(e, v) => setState(v.value)} />
					<Tooltip el="div" text="Confirm" direction="b"><Button iconName="check" primary/></Tooltip>
					<Tooltip el="div" text="Cancel" direction="bl"><Button iconName="close"/></Tooltip>
				</Stack>
				<Stack spacing="1" className="m-t-3">
					<Select options={options} value={state} onChange={(e, v) => setState(v.value)} small />
					<Tooltip el="div" text="Confirm" direction="b"><Button small iconName="check" primary/></Tooltip>
					<Tooltip el="div" text="Cancel" direction="bl"><Button small iconName="close"/></Tooltip>
				</Stack>
			</Form>
		)
	}}
</State>

Loading

Add the loading prop to the button and it disables and gives a loading animation. Useful for preventing double submissions on forms. The button width will not change.

const LoadingButton = (props) => {
	const { timeout = 2000 } = props;
	const [loading, setLoading] = React.useState(false);

	const onClickHandler = () => {
		setLoading(true);
		setTimeout(() => setLoading(false), timeout);
	}

	return <Button onClick={onClickHandler} loading={loading} {...props} />;
}

render (
	<div>
		<LoadingButton primary>Click Me</LoadingButton>
		<br/><br/>
		<LoadingButton primary timeout={3000}>A Longer Example</LoadingButton>
		<br/><br/>
		<LoadingButton primary full timeout={5000}>A Really Long Example</LoadingButton>
	</div>
)

Selected

Use the selected state when a Button needs to visually appear active, such as when an Action Menu associated with the Button is open.

<Stack spacing={3} justifyContent="space-around" className="w-100" wrap="wrap">
    <Stack direction="column" spacing={3} className="p-b-2">
		<ButtonGroup attached>
			<Button primary>Refresh</Button>
			<Button primary iconName="expand_more" selected />
		</ButtonGroup>
		<ButtonGroup attached>
			<Button primary outline>Refresh</Button>
			<Button primary outline iconName="expand_more" selected />
		</ButtonGroup>
		<ButtonGroup attached>
			<Button primary fill='subtle'>Refresh</Button>
			<Button primary fill='subtle' iconName="expand_more" selected />
		</ButtonGroup>
    </Stack>
    <Stack direction="column" spacing={3} className="p-b-2">
		<ButtonGroup attached>
			<Button>Refresh</Button>
			<Button iconName="expand_more" selected />
		</ButtonGroup>
		<ButtonGroup attached>
			<Button outline>Refresh</Button>
			<Button outline iconName="expand_more" selected />
		</ButtonGroup>
		<ButtonGroup attached>
			<Button fill='subtle'>Refresh</Button>
			<Button fill='subtle' iconName="expand_more" selected />
		</ButtonGroup>
    </Stack>

    <Stack direction="column" spacing={3} className="p-b-2">
		<ButtonGroup attached>
			<Button negative>Refresh</Button>
			<Button negative iconName="expand_more" selected />
		</ButtonGroup>
		<ButtonGroup attached>
			<Button negative outline>Refresh</Button>
			<Button negative outline iconName="expand_more" selected />
		</ButtonGroup>
		<ButtonGroup attached>
			<Button negative fill='subtle'>Refresh</Button>
			<Button negative fill='subtle' iconName="expand_more" selected />
		</ButtonGroup>
    </Stack>
</Stack>

Content Guidelines

Button name should describe what it does

A user should be able to use the button name to predict what will happen when they click it.

Buttons should action-oriented, pairing a verb and a supporting noun, and be 2 to 3 words long. Common actions like “Save,” “Close,” “Cancel,” or “OK” don’t require a supporting noun.

Be concise and consistent

Avoid unnecessary words and articles such as the, an, or a. Never include punctuation in button text and avoid button text that requires punctuation. Always write button text in title case. Capitalize the first word, the last word, and all major words in between. Never use emoji or exclamation points.

Button name should match destination

When a button opens a modal or takeover, the destination’s title should match the button text.

Button labeled Add Transaction opens a modal titled “Add transaction”

Button labeled Add Transaction opens a modal titled “Create new invoice”.

Technical Examples

Click Action

Use the onClick prop to pass a function to the button.

Linked

The standard button component uses a span element because most buttons will be passed a function. If you pass the button a href prop, it will become an a element and click through to the url.

You can pass Button through the trigger prop of the ActionMenu.

<State initial={false}>
    {([open, setOpen]) => {
		const handleClick = () => setOpen(!open);
		const handleClickOutside = () => setOpen(false);

        return (
			<ActionMenu
				trigger={<Button onClick={handleClick} small iconName="expand_more" iconPosition="right">Use the force</Button>}
				sharp={false}
				width="auto"
				direction="br"
				open={open}
				onClickOutside={handleClickOutside}
			>
				<ActionMenu.Item>Precognition</ActionMenu.Item>
				<ActionMenu.Item>Psychometry</ActionMenu.Item>
				<ActionMenu.Item>Telepathy</ActionMenu.Item>
				<ActionMenu.Item>Shadow Vision</ActionMenu.Item>
				<ActionMenu.Item>Levitation</ActionMenu.Item>
			</ActionMenu>
        )
    }}
</State>

Best Practices

Use the same button sizes within an action area
Prioritize the most important actions. Too many calls to action can cause confusion and make users unsure of what to do next.
Using several styles on one page may be confusing to user. Try to avoid using more than 3 styles on a screen.

For a text button inline in a paragraph, use a Link.
To group Buttons together, use a Button Group.

Importing

import { Button } from '@servicetitan/design-system';

Button