Button

Buttons are used primarily for actions, such as “Add”, “Close”, “Cancel”, or “Save”. Plain buttons, which look similar to links, are used for less important or less commonly used actions, such as “view shipping settings”.

  import { Button } from "@chepe/ui";
 
  export default function App() {
    return <Button>Hello world!</Button>;
  }

Features

• ✅ Focus is fully managed.
• ✅ Full keyboard navigation.

Anatomy

Roles

User Interactive, Focusable, Disableable, Hoverable

Layout

Only use one primary button in a layout for the most important action. If there are more than two buttons with equal priority, all buttons should have neutral backgrounds.

When there are many available minor actions, use the outline, subtle, or transparent appearances on all buttons to avoid a busy layout.

Always give the primary button action prominent placement, either on top of or to the left of other actions. In right-to-left languages, primary button placement will be on the right

Elements

1. Label text
2. Container
3. Icon (optional)

Types

Buttons have three different types:

• Variant
• Color
• Size

Variants

import { Button } from "@chepe/ui";
 
export default function App() {
  return (
    <Stack horizontal>
      <Button>Normal</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="text">Text</Button>
      <Button variant="link">Link</Button>
    </Stack>
  );
}

Colors

import { Button } from "@chepe/ui";
 
export default function App() {
  return (
    <Stack horizontal>
      <Button color="default">default</Button>
      <Button color="secondary">secondary</Button>
      <Button color="success">success</Button>
      <Button color="warning">warning</Button>
      <Button color="error">error</Button>
      <Button color="info">info</Button>
    </Stack>
  );
}

Sizes

import { Button, div } from "@chepe/ui";
 
export default function App() {
  return (
    <Stack horizontal>
      <Button size="small">Small</Button>
      <Button size="medium">Medium</Button>
      <Button size="large">Large</Button>
    </Stack>
  );
}

API Reference

interface ButtonProps

Behaviors

States: For each button action type and emphasis style there are five button states — enabled, hover, active, focus and disabled.

Accessibility

Buttons can have different states that are visually and programmatically conveyed

• Use the ariaControls prop to add an aria-controls attribute to the button. Use the attribute to point to the unique id of the content that the button manages.
• If a button expands or collapses adjacent content, then use the ariaExpanded prop to add the aria-expanded attribute to the button. Set the value to convey the current expanded (true) or collapsed (false) state of the content.
• Use the disabled prop to set the disabled state of the button. This prevents users from being able to interact with the button, and conveys its inactive state to assistive technologies.
• Use the pressed prop to add an aria-pressed attribute to the button.

Keyboard support

Buttons use browser defaults for keyboard interactions.

Give buttons keyboard focus with the tab key (or shift + tab when tabbing backwards) Activate buttons with the enter/return key or the space key

When the button has focus:

“Space”: Activates the button.

“Enter”: Activates the button.

Following button activation, focus is set depending on the type of action the button performs. For example:

If activating the button opens a dialog, the focus moves inside the dialog.

If activating the button closes a dialog, focus typically returns to the button that opened the dialog unless the function performed in the dialog context logically leads to a different element. For example, activating a cancel button in a dialog return focus to the button that opened the dialog. However, if the dialog were confirming the action of deleting the page from which it was opened, the focus would logically move to a new context.

If activating the button does not dismiss the current context, then focus typically remains on the button after activation, e.g., an Apply or Recalculate button.

If the button action indicates a context change, such as move to next step in a wizard or add another search criteria, then it is often appropriate to move focus to the starting point for that action.

If the button is activated with a shortcut key, the focus usually remains in the context from which the shortcut key was activated. For example, if Alt + U were assigned to an "Up" button that moves the currently focused item in a list one position higher in the list, pressing Alt + U when the focus is in the list would not move the focus from the list.

WAI-ARIA Roles, States, and Properties

The button has role of button.

The button has an accessible label. By default, the accessible name is computed from any text content inside the button element. However, it can also be provided with aria-labelledby or aria-label.

If a description of the button's function is present, the button element has aria-describedby set to the ID of the element containing the description.

When the action associated with a button is unavailable, the button has aria-disabled set to true.

If the button is a toggle button, it has an aria-pressed state. When the button is toggled on, the value of this state is true, and when toggled off, the state is false.

Custom key events

Use the onKeyDown, onKeyPress, and onKeyUp props to create custom events for buttons. With these props, you can use buttons to create complex, custom interactions like drag-and-drop interfaces.

Since these props introduce non-standard features to buttons, make sure to include accessible instructions so that users can understand how to use these features.

Guidelines

Usage

Buttons are clickable elements that allow users to take action.

Use buttons for taking important actions in the UI like submitting a response, moving to the next step or committing a change. For navigating to another place, use a link instead.

Content

Buttons need to be clear and predictable. Users should be able to anticipate what will happen when they select a button. Never mislead someone by mislabeling a button.

Buttons should always lead with a strong verb that encourages action. To provide enough context to users use a “verb” + “noun” on buttons except in the case of common actions like “done”, “cancel” or “ok”

Buttons versus links

Buttons are used primarily for actions, such as “Add”, “Close”, “Cancel”, or “Save”. Plain buttons, which look similar to links, are used for less important or less commonly used actions, such as “view shipping settings”.

Links are used primarily for navigation, and usually appear within or directly following a sentence.

The HTML that renders for the Button and Link components carries meaning. Using these components intentionally and consistently results in:

• a more inclusive experience for assistive technology users
• a more cohesive visual experience for sighted users
• products that are easier to maintain at scale

Types of buttons

It's important to make a distinction here: when people talk about buttons on the web, they're probably talking about one of three things:

1. A <button> element which, depending on its type attribute (submit, reset or button), triggers some kind of action: submitting a form, clearing a form, or triggering a JavaScript function.
2. An <input> element with one of the three types: submit, reset or button. These are functionally almost identical to a <button> element with the same type attribute.
3. Any other interactive HTML element that looks like a button, but isn’t a <button> element. This category includes ‘call-to-action’ links designed to look like buttons.

In most cases, it’s preferable to use a <button> instead of the corresponding <input>: With a <button> the label text goes between opening and closing tags, allowing you to include other HTML elements inside the label; with <input> you’re restricted to using the value attribute which only has support for text strings.

Related Content

Appears on Patterns

Menu button A menu button shows a menu of options. Unlike the split button, the menu button does not surface a primary action. It is often styled as a typical button with a downward pointing arrow or triangle to hint that activating the button will display a menu.

Toggle button A toggle button is a two-state behavior that switches a state between on and off. A button’s rest state indicates “off” while the selected state indicates “on.” The button and compound button types can have toggle behavior.

Related Components

• Button Group
• Link
• Form Elements