> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Button – Design
> Buttons are clickable UI elements that trigger an action or event.
export const LiveCode = ({children, customHeight, clickToLoad, example, fullWidth, fullHeight, hideCodeInLiveCode, screenshot, screenshotOnly, showCode: showCodeProp}) => {
const SCREENSHOTS_BASE = "https://servicetitan.github.io/anvil2-docs-live-code/screenshots";
const STACKBLITZ_BASE = "https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples";
const [showCodeBlock, setShowCodeBlock] = useState(showCodeProp ?? false);
const [isLocalOverride, setIsLocalOverride] = useState(false);
useEffect(() => {
const examplePath = `/images/live-code-screenshots-tmp/${example}.png`;
fetch(examplePath, {
method: "HEAD"
}).then(r => {
if (r.ok) setIsLocalOverride(true);
}).catch(() => {});
}, [example]);
const screenshotBase = isLocalOverride ? "/images/live-code-screenshots-tmp" : SCREENSHOTS_BASE;
if (screenshotOnly) {
return
;
}
if (screenshot) {
return
{!showCodeProp ?
: null}
StackBlitz demo
;
}
};
export const CodePreviewPlaceholder = ({double, fullWidth}) => {
const single = ;
return double ?
{single}
{single}
: single;
};
## Anatomy
The Button consists of three primary elements that work together to trigger actions or events.
1. Container
2. Text label
3. Icon
## Options
The Button supports multiple appearances, sizes, and icon configurations to accommodate various action scenarios.
### Appearances
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
| 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
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
| 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
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
import FileUpload from "@servicetitan/anvil2/assets/icons/material/round/file_upload.svg";
import KeyboardArrowDown from "@servicetitan/anvil2/assets/icons/material/round/keyboard_arrow_down.svg";
import Edit from "@servicetitan/anvil2/assets/icons/material/round/edit.svg";
function App() {
return (
);
}
export default App;
```
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](#icons-in-buttons) 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
```tsx lines theme={null}
import { ButtonCompound, Avatar } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
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
```tsx lines theme={null}
import { ButtonLink, Flex } from "@servicetitan/anvil2";
function App() {
return (
Link to Web
);
}
export default App;
```
The **Button Link** is a specialized Button component that uses an `` 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**](/docs/web/components/link/design) 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
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
#### Danger Secondary
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
#### Secondary
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
#### Ghost
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
#### Danger Primary
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
#### Disabled
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
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
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
Buttons fill all available space, wrapping only when no space remains. Text is center-aligned when wrapping.
### Widths
```tsx lines theme={null}
import { Button, Grid } from "@servicetitan/anvil2";
import Edit from "@servicetitan/anvil2/assets/icons/material/round/edit.svg";
function App() {
return (
);
}
export default App;
```
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
```tsx lines theme={null}
import { Button, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
Button text is typically centered. Use left-aligned text when aligning with specific layout elements or when stacking multiple buttons vertically.
## Usage Guidelines
Use the Button to denote most forms of actions on the page.
### When not to use
In general, buttons should not be used for navigation. See the Link comparison below for more details related to Links. For other navigational contexts, consider the Tab or Side Nav.
### 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
```tsx lines theme={null}
import { Button, Grid, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**Do**
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](/docs/web/components/dialog/design), [Drawers](/docs/web/components/drawer/design), and [Alerts](/docs/web/components/alert/design) 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
```tsx lines theme={null}
import { Button, Grid, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**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
```tsx lines theme={null}
import { Button, Grid, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**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](/docs/web/patterns/forms#button-alignment).
##### 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.
```tsx lines theme={null}
import { Button, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Button, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**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.
```tsx lines theme={null}
import { Button, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Button, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**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.
```tsx lines theme={null}
import { Button, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**Do**
```tsx lines theme={null}
import { Button, Flex } from "@servicetitan/anvil2";
function App() {
return (
);
}
export default App;
```
**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
```tsx lines theme={null}
import { Button, Tooltip } from "@servicetitan/anvil2";
import Edit from "@servicetitan/anvil2/assets/icons/material/round/edit.svg";
function App() {
return (
Tooltip Content
);
}
export default App;
```
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](/docs/accessibility/labels-and-ctas#buttons-and-links).
