Button

Buttons communicate the action that will occur when the user clicks them. They communicate calls to action to the user and allow users to interact with pages in a variety of ways. They contain a text label to describe the action, and an icon if appropriate.

Import

import { Button } from '@contentful/f36-components';
// or
import { Button } from '@contentful/f36-button';

Examples

Variants

Button has 5 different variants:

• Primary - Used for the most important actions in any scenario. Don’t use more than one primary button in a section or screen to avoid overwhelming users.
• Secondary - Used for secondary actions, the most commonly used button type.
• Positive - For use when the action has a positive connotation such as creating or publishing a new entity.
• Negative - For destructive actions - when something can't be undone. For example, deleting entities.
• Transparent - For having an unstylized button.

Open in Playground
function ButtonVariantsExample() {
  return (
    <Stack>
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="negative">Negative</Button>
      <Button variant="positive">Positive</Button>
      <Button variant="transparent">Transparent</Button>
    </Stack>
  );
}
function ButtonVariantsExample() {
  return (
    <Stack>
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="negative">Negative</Button>
      <Button variant="positive">Positive</Button>
      <Button variant="transparent">Transparent</Button>
    </Stack>
  );
}
Hide source

Sizes

Button has 3 different sizes:

Open in Playground
function ButtonSizesExample() {
  return (
    <Stack>
      <Button size="large">Large</Button>
      <Button size="medium">Medium</Button>
      <Button size="small">Small</Button>
    </Stack>
  );
}
function ButtonSizesExample() {
  return (
    <Stack>
      <Button size="large">Large</Button>
      <Button size="medium">Medium</Button>
      <Button size="small">Small</Button>
    </Stack>
  );
}
Hide source

States

Open in Playground
function ButtonStatesExample() {
  return (
    <Stack>
      <Button isActive>Active</Button>
      <Button isDisabled>Disabled</Button>
      <Button isLoading>Loading</Button>
    </Stack>
  );
}
function ButtonStatesExample() {
  return (
    <Stack>
      <Button isActive>Active</Button>
      <Button isDisabled>Disabled</Button>
      <Button isLoading>Loading</Button>
    </Stack>
  );
}
Hide source

Full width

Open in Playground
function ButtonFullWidthExample() {
  return <Button isFullWidth>Full Width Button</Button>;
}
function ButtonFullWidthExample() {
  return <Button isFullWidth>Full Width Button</Button>;
}
Hide source

Rendered as a tag

By default, button is rendered as a button tag. But you can change it to a tag, by providing as prop. Don't forget to pass href prop as well.

Open in Playground
function ButtonAsAExample() {
  return (
    <Button as="a" href="https://www.contentful.com/" target="_blank">
      Visit Contentful
    </Button>
  );
}
function ButtonAsAExample() {
  return (
    <Button as="a" href="https://www.contentful.com/" target="_blank">
      Visit Contentful
    </Button>
  );
}
Hide source

With icons

You can add an icon by providing the following props:

• startIcon - adds icon to the left side of the button
• endIcon - adds icon to the right side of the button

Open in Playground
function ButtonWithIconExample() {
  return (
    <Stack>
      <Button startIcon={<PlusIcon />}>Add</Button>
      <Button endIcon={<ChevronDownIcon />}>Menu</Button>
    </Stack>
  );
}
function ButtonWithIconExample() {
  return (
    <Stack>
      <Button startIcon={<PlusIcon />}>Add</Button>
      <Button endIcon={<ChevronDownIcon />}>Menu</Button>
    </Stack>
  );
}
Hide source

Props (API reference)

• Name

  as

  Description

  The element used for the root node.

  HTML Tag or React Component (e.g. div, span, etc)
• Name

  children

  ReactNode
• Name

  className

  Description

  CSS class to be appended to the root element

  string
• Name

  endIcon

  Description

  Expects any of the icon components. Renders the icon aligned to the end

  ReactElement<any, string | JSXElementConstructor<any>>
• Name

  isActive

  Description

  Applies active styles

  false

  true
• Name

  isDisabled

  Description

  Disabled interaction and applies disabled styles

  false

  true
• Name

  isFullWidth

  Description

  Forces button to take 100% of the container

  false

  true
• Name

  isLoading

  Description

  Adds loading indicator icon and disables interactions

  false

  true
• Name

  size

  Description

  Determines size variation of Button component

  "small"

  "medium"

  "large"
• Name

  startIcon

  Description

  Expects any of the icon components. Renders the icon aligned to the start

  ReactElement<any, string | JSXElementConstructor<any>>
• Name

  testId

  Description

  A [data-test-id] attribute used for testing purposes

  string
• Name

  variant

  Description

  Determines style variation of Button component

  "negative"

  "positive"

  "primary"

  "secondary"

  "transparent"

Content guidelines

• Don't use more than one primary button in a section or screen to avoid overwhelming users.
• Start labels with action verbs. If the button is part of an action dialog, make sure it matches the dialog header.
• Position buttons in consistent places in the interface
• Use the right button for the primary action, if the button group is right-aligned
• Use the left button for the primary action, if the button group is left- or center-aligned
• Reduce complexity by using a small number of actions. Too many actions can create confusion when having to decide
• For buttons that are used to cancel destructive actions: label them "Never mind" or similar, instead of cancel. It makes things much easier for users to understand.
• UI usage - Button labels should be no longer than 3 words
• Webpage usage - Button labels should be no longer than 5 words

Accessibility

• When Button is focused, both the Space and Enter keys will activate the button.
• All Button variants are checked in terms of color contrast and passed all the requirements.
• Buttons have a focus state when using keyboard navigation.