Button - Web

For development, import Button from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Button consists of three primary elements that work together to trigger actions or events.

Container
Text label
Icon

Options

The Button supports multiple appearances, sizes, and icon configurations to accommodate various action scenarios.

Appearances

Appearance	When to use
Primary	Reserved for important, essential actions on the page. Avoid using more than 3 primary actions in the same view.
Secondary	Used as the most common style of actions.
Ghost	For less prominent actions, and a good fit for icon-only actions.

Sizes

Size	Height
Extra Small	28px
Small	32px
Medium	40px
Large	48px

Extra small buttons should only be used on desktop devices, as they do not meet the 44x44px tap target required for mobile.

Icons

Icons can be placed both before and after the Button’s text label, and can even replace the text label as an Icon Button. See the Button Icon usage guidelines on when to use icons, and accessibility considerations when using icons.

Button Compound

A Button Compound is a standalone component that provides button interactivity to another component. This can be useful for components such as anAvatar, which by themselves lack interactivity.

Button Compound Option Circular

The shape of the Button Compound can be changed to conform to the shape of the component it’s overlaying, such as an Avatar.

Button Link

The Button Link is a specialized Button component that uses an <a> tag under the hood. It gives you the visual style of a button with the correct HTML semantics of a link, making it ideal for actions that navigate to a new page. The Link Button is its reverse: a Button component styled to look like a simple text link. Use it when an action doesn’t involve navigation but you need a link’s visual appearance, such as for triggering a modal.

Behavior

The Button responds to user interaction with distinct visual states and flexible layout behaviors.

Visual States

Primary

Danger Secondary

Secondary

Ghost

Danger Primary

Disabled

The disabled style is consistent across each button variant. This style is useful when preventing user clicks when an action isn’t available or when a submission of some kind is taking place.

Text wrap

Buttons fill all available space, wrapping only when no space remains. Text is center-aligned when wrapping.

Widths

In general, Buttons should match the width of their text. Container width works well when aligning with specific layout elements. Button Icon width always equals its height.

Left-aligned Text

Button text is typically centered. Use left-aligned text when aligning with specific layout elements or when stacking multiple buttons vertically.

Usage Guidelines

Standard	Requirement
DoDenote actions	Use the Button to denote most forms of actions on the page.
DoRecommended emphasis pairings	Most combinations of Primary, Secondary, and Ghost are allowed; use the hierarchy that best represents an action’s relative importance, and never use more than one Primary action; see Button Pairing.
DoLeft-align stacked secondary Buttons	When several Buttons are stacked vertically, use the Secondary variant, left-align the text, and give each Button the same width; see Button Alignment.
DoButton Compound for static components	A component such as an Avatar lacks interactivity on its own and needs button behavior.
DoButton Compound to match wrapped shape	The interactive area must conform to the shape of the component it wraps, such as the circular shape for an Avatar.
DoButton Link for navigation with button styling	An action navigates to a new page and needs a button’s visual style with the semantics of a link.
Don’tMultiple Primary or Danger actions	Don’t pair multiple Primary or multiple Danger actions together — each should only occur once in a context; see Don’t use these pairings.
Don’tUse for navigation	In general, buttons should not be used for navigation. See the Link comparison below for more details. For other navigational contexts, consider the Tab or Side Nav.

Avoid using the Button Compound for:

Clickable cards – A whole card needs to be clickable; use the Interactive Card instead.
Standard actions – The control only needs a text label or icon; use the Button instead.

Avoid using the Button Link for:

Most navigation – Links are the preferred choice for navigating; use the Link instead.
Actions that don’t navigate – The control runs an action in place; use the Button instead.
Non-navigating actions that need a link’s appearance – Use the Link Button instead.

Alternatives

Button vs Link

In general, Buttons are used to denote an action, while a Link is used to denote navigation. This distinction in practice can be blurry.

When navigating

In general, Links are the preferred choice for navigating. There are a few scenarios when a Button may be used however:

Use a Button when emphasis is needed. Sometimes a page’s call to action is navigating somewhere else.
Use a Button when navigation is mixed with actions.

With Actions

In general, Buttons are the preferred choice for actions. A Link however may be used when the action priority is low and space is tight.

With triggering overlays

Triggering an overlay UI can be treated like navigation.

How to Use

Button Pairing

There are 3 levels of emphasis in our Buttons: primary, secondary, and ghost. This corresponds to an emphasis scheme of high, medium, and low emphasis.

Recommended pairings

Most combinations of Primary, Secondary, and Ghost are allowed. In general, use the hierarchy that best represents its relative importance on the page.

Be consistent within a product area.
There should never be more than 1 Primary action. There is no upper limit to how many Secondary or Ghost actions could exist.
Some components, such as Dialogs, Drawers, and Alerts have Button pairing standards already, and those should be used when possible.
Icon-only actions are frequently represented as Ghost actions.
A Cancel action is generally a Secondary action.

Caution when pairing

Caution

While these pairings are allowed, caution should be used with them. Three levels of Button hierarchy in one grouping is usually excessive, consider simplifying it to two levels.

Don’t use these pairings

Don’t

These pairings should be avoided. Primary actions are meant to only occur once in a context, multiple primaries should not happen.

Icons in Buttons

In general, icons should only be used in Buttons when a user can easily associate the icon with the action.

Use caution with Icon-only Buttons

While icon-only buttons can save space on the page, the meaning behind icons is not universally understood. Often, this requires users to explore and later recall what each icon does to understand the action.

Always include a Tooltip with Icon-only Buttons

All Icon-only buttons should include a Tooltip that appears on hover and focus, describing what the Button would do.

Button Alignment

Refer to the Button alignment guidance from the Form pattern.

Left-aligned Buttons

In scenarios where you have several Buttons stacked vertically, use the Secondary variant and left-align the text. Each button should have the same width.

Don’t

Content

Content within the Button should clearly communicate the action it will perform.

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 be 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.

Don’t

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.

Don’t

Button name should match destination

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

Keyboard Interaction

Users can navigate the Button using standard keyboard controls.

Key	Interaction
Space or Enter	Engages the button action

Buttons using an href will also use this keyboard combination.

Accessibility

Anvil provides most of the accessibility needs for buttons out of the box, and only needs some additional considerations for library users.

Provide labels for Icon Buttons

Regardless of whether or not a label is visible on the page, a label should be provided to describe the action for both screen readers and for users who focus on the element. For more guidance on button labels and accessibility, see button accessibility best practices.

Code

Implementation
Button Props
ButtonCompound Props
ButtonLink Props

Common Examples

import { Button, ButtonCompound, ButtonLink, Card } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <>
      <Button onClick={console.log}>Click me</Button>
      <ButtonCompound onClick={console.log}>
        <Card>Click me</Card>
      </ButtonCompound>
      <ButtonLink href="#">Click me</ButtonLink>
    </>
  );
}

The Button component can be used in the same way that you would use an HTML button element, while the ButtonLink component can be used in the same way that you would use an HTML a element.

Form Submit

The type prop can be used to alter the default functionality of the button. A common use case is to use type="submit" in order to submit the content of a form.

<form onSubmit={handleSubmit}>
  <TextInput name="firstName" label="First Name" required />
  <Button type="submit">Submit</Button>
</form>

Button links

In general, Links should be used for navigating to other pages or website. To create a link that is styled like a button, use the ButtonLink component.

<div>
  <div>
    <BodyText>
      A project label can be attached to expense items like timesheet activities
      to provide a visual representation of expense spending.
    </BodyText>
    <br />
    <br />
    <ButtonLink href="#">Learn more</ButtonLink>
  </div>
</div>

Using button compounds to make components interactive

To add interactivity to components that are usually static, such as avatars, use the ButtonCompound component.

<ButtonCompound shape="circular" onClick={handleClick}>
  <Avatar {...avatarProps} />
</ButtonCompound>

Interactive cards

To make cards clickable, use the InteractiveCard component. It supports nested interactive elements without accessibility violations.

AI Mark

Use the aiMark prop to display an AI indicator. aiMark accepts a boolean, or one of:

"mark"
"chat"
"edit"
"form"
"mic"
"search"

The aiMark prop cannot be used together with a before icon (a single icon Svg or icon={{ before: Svg }}).

Button usage	`aiMark`	`icon` allowed?
With `children`	`true` or an AI icon name	Only after: use `icon={{ after: Svg }}` or omit `icon`. You cannot use a before icon or a single `icon` Svg.
Icon-only (no `children`)	`true` or an AI icon name	No. Do not pass `icon`. Only the AI icon is shown. Always provide `aria-label`.

With children:

<Button appearance="primary" aiMark>Generate</Button>
<Button appearance="secondary" aiMark icon={{ after: ArrowForward }}>Report</Button>

Icon-only AI:

<Button aria-label="AI action" aiMark />
<Button aria-label="AI chat" aiMark="chat" />

Minimum width for buttons

If a Button component has any children, it will have a 5rem minimum width. This is not applied in icon-only buttons using the icon prop. In some cases, such as when adding a Badge as a child of a Button component without any text, this can lead to unexpected width changes.Either override the width and minWidth of the Button component, or make the Badge a sibling of the Button inside of a div with relative positioning.

// option 1
<Button
  aria-label="filters button"
  icon={FilterIcon}
  style={{ width: '2rem', minWidth: '2rem' }}
>
  <Badge aria-label="2 active filters">2</Badge>
</Button>

// option 2
<div style={{ position: 'relative', display: 'inline-block '}}>
  <Button aria-label="filters button" icon={FilterIcon} />
  <Badge aria-label="2 active filters">2</Badge>
</div>

React Accessibility

Icon-only buttons

<Button icon={Edit} aria-label="Edit" />

Use aria-label or aria-labelledby for a button without any text.

<Button icon={Edit} />

Don’t

Provide only an icon for screen readers to read.For more guidance on button labels and accessibility, see button accessibility best practices.

<Button
  appearance="primary"
  size="medium"
  icon={StarIcon}
  loading={false}
  aiMark={true}
  onClick={() => console.log("Clicked")}
>
  Click me
</Button>

`Button` Props

default:"false"

Shows an AI indicator. When set with button text, a leading icon (plain Svg or icon.before) is not rendered—the AI icon is used instead. On an icon-only button, icon is not rendered. Use icon={{ after: Svg }} for a trailing icon with text.

"primary" | "secondary" | "ghost" | "danger" | "danger-secondary"

default:"secondary"

ReactNode

Svg | { before: Svg } | { after: Svg }

The SVGR library imports *.svg files as React components, so icon can accept either a React component, or an object with before or after key to specify the placement of the icon.

boolean

default:"false"

Setting this to true will put the button into a loading state.

"xsmall" | "small" | "medium" | "large"

default:"medium"

<ButtonCompound shape="circular" onClick={handleClick}>
  <Avatar name="John Doe" />
</ButtonCompound>

`ButtonCompound` Props

"pill" | "circular" | "rounded"

default:"rounded"

<ButtonLink
  href="/page"
  appearance="primary"
  size="medium"
  icon={StarIcon}
  loading={false}
  disabled={false}
>
  Click me
</ButtonLink>

`ButtonLink` Props

"primary" | "secondary" | "ghost" | "danger" | "danger-secondary"

default:"secondary"

ReactNode

boolean

default:"false"

Svg | { before: Svg } | { after: Svg }

The SVGR library imports *.svg files as React components, so icon can accept either a React component, or an object with before or after key to specify the placement of the icon.

boolean

default:"false"

Setting this to true will put the button into a loading state.

"xsmall" | "small" | "medium" | "large"

default:"medium"

​Anatomy

​Options

​Appearances

​Sizes

​Icons

​Button Compound

​Button Compound Option Circular

​Button Link

​Behavior

​Visual States

​Primary

​Danger Secondary

​Secondary

​Ghost

​Danger Primary

​Disabled

​Text wrap

​Widths

​Left-aligned Text

​Usage Guidelines

​Alternatives

​Button vs Link

When navigating

With Actions

With triggering overlays

​How to Use

​Button Pairing

Recommended pairings

​Caution when pairing

​Don’t use these pairings

​Icons in Buttons

Use caution with Icon-only Buttons

Always include a Tooltip with Icon-only Buttons

​Button Alignment

Left-aligned Buttons

​Content

​Button name should describe what it does

​Be concise and consistent

​Button name should match destination

​Keyboard Interaction

​Accessibility

​Provide labels for Icon Buttons

​Code

​Common Examples

​Form Submit

​Button links

​Using button compounds to make components interactive

​Interactive cards

​AI Mark

​Minimum width for buttons

​React Accessibility

​Icon-only buttons

​Button Props

​ButtonCompound Props

​ButtonLink Props

Anatomy

Options

Appearances

Sizes

Icons

Button Compound

Button Compound Option Circular

Button Link

Behavior

Visual States

Primary

Danger Secondary

Secondary

Ghost

Danger Primary

Disabled

Text wrap

Widths

Left-aligned Text

Usage Guidelines

Alternatives

Button vs Link

How to Use

Button Pairing

Caution when pairing

Don’t use these pairings

Icons in Buttons

Button Alignment

Content

Button name should describe what it does

Be concise and consistent

Button name should match destination

Keyboard Interaction

Accessibility

Provide labels for Icon Buttons

Code

Common Examples

Form Submit

Button links

Using button compounds to make components interactive

Interactive cards

AI Mark

Minimum width for buttons

React Accessibility

Icon-only buttons

`Button` Props

`ButtonCompound` Props

`ButtonLink` Props