Skip to content
Cimpress UI

Button API

Usage guidelinesAPI

Import

Section titled “Import”

Cimpress UI exports several different button-related components. Use the version that’s appropriate for your use case.

  • Button: has a visible label, performs an action
  • LinkButton: has a visible label, performs navigation
  • IconButton: has no visible label (icon-only), performs an action
  • IconLinkButton: has no visible label (icon-only), performs navigation
import { Button, IconButton, IconLinkButton, LinkButton } from '@cimpress-ui/react';

Accessibility notes

Section titled “Accessibility notes”

Button and IconButton can be activated by pressing Enter or Space, similar to a native HTML button.

LinkButton and IconLinkButton can be activated by pressing Enter, similar to a native HTML link.

IconButton and IconLinkButton should have an aria-label prop defined to identify the function of the button to assistive technologies. Button and IconButton in a loading state should have a loadingLabel prop defined to identify the loading state to assistive technologies. See our accessibility guide for more details.

Buttons with a variant="tertiary" prop have a transparent background. This variant should only be used on backgrounds that provide adequate contrast.

API reference

Section titled “API reference”

Button

Section titled “Button”

Displays a labelled button that allows users to perform an action.

See button usage guidelines.

ref Ref<HTMLButtonElement>

The ref type for this component.

ButtonProps
children * StringLikeChildren

The text displayed on the button.

variant 'primary' | 'secondary' | 'tertiary'

Determines the visual appearance of the button.

Defaults to 'secondary' .
tone 'base' | 'critical'

Determines the color tone of the button.

Defaults to 'base' .
size 'small' | 'medium' | 'large'

The size of the button.

Defaults to 'medium' .
fullWidth boolean

Whether the button should take up the whole available width.

Defaults to false .
iconStart ReactNode

An icon displayed before the button text.

iconEnd ReactNode

An icon displayed after the button text.

isLoading boolean

Whether the button is in a loading state. This disables the button and replaces its contents with a spinner.

Defaults to false .
loadingLabel string

A string that identifies the loading state to assistive technologies. It will be announced by screen readers together with the button label. You must provide this prop if isLoading is true.

id string

The element's unique identifier. See MDN.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

UNSAFE_className string

Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.

UNSAFE_style CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

aria-label string

Defines a string value that labels the current element.

aria-labelledby string

Identifies the element (or elements) that labels the current element.

aria-describedby string

Identifies the element (or elements) that describes the object.

aria-details string

Identifies the element (or elements) that provide a detailed, extended description for the object.

isDisabled boolean

Whether the button is disabled.

type 'button' | 'reset' | 'submit'

The behavior of the button when used in an HTML form.

Defaults to 'button' .
onHoverStart (e: HoverEvent) => void

Handler that is called when a hover interaction starts.

onHoverEnd (e: HoverEvent) => void

Handler that is called when a hover interaction ends.

onPress (e: PressEvent) => void

Handler that is called when the press is released over the target.

form string

The <form> element to associate the button with. The value of this attribute must be the id of a <form> in the same document.

name string

Submitted as a pair with the button's value as part of the form data.

value string

The value associated with the button's name when it's submitted with the form data.

StyleProps
margin Responsive<Spacing | "auto">

The amount of margin applied to all edges of this component.

marginX Responsive<Spacing | "auto">

The amount of margin applied to the left and right edges of this component. Takes priority over margin.

marginY Responsive<Spacing | "auto">

The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.

marginTop Responsive<Spacing | "auto">

The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.

marginRight Responsive<Spacing | "auto">

The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.

marginBottom Responsive<Spacing | "auto">

The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.

marginLeft Responsive<Spacing | "auto">

The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

LinkButton

Section titled “LinkButton”

Displays a labelled button that allows users to navigate to another page or resource.

See button usage guidelines.

ref Ref<HTMLAnchorElement>

The ref type for this component.

LinkButtonProps
children * StringLikeChildren

The text displayed on the button.

href * string

A URL to link to.

variant 'primary' | 'secondary' | 'tertiary'

Determines the visual appearance of the button.

Defaults to 'secondary' .
tone 'base' | 'critical'

Determines the color tone of the button.

Defaults to 'base' .
size 'small' | 'medium' | 'large'

The size of the button.

Defaults to 'medium' .
fullWidth boolean

Whether the button should take up the whole available width.

Defaults to false .
iconStart ReactNode

An icon displayed before the button text.

iconEnd ReactNode

An icon displayed after the button text.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

UNSAFE_className string

Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.

UNSAFE_style CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

aria-label string

Defines a string value that labels the current element.

aria-labelledby string

Identifies the element (or elements) that labels the current element.

aria-describedby string

Identifies the element (or elements) that describes the object.

aria-details string

Identifies the element (or elements) that provide a detailed, extended description for the object.

routerOptions undefined

Options for the configured client side router.

isDisabled boolean

Whether the link is disabled.

hrefLang string

Hints at the human language of the linked URL. SeeMDN.

target HTMLAttributeAnchorTarget

The target window for the link. See MDN.

rel string

The relationship between the linked resource and the current page. See MDN.

download string | boolean

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.

ping string

A space-separated list of URLs to ping when the link is followed. See MDN.

referrerPolicy HTMLAttributeReferrerPolicy

How much of the referrer to send when following the link. See MDN.

onHoverStart (e: HoverEvent) => void

Handler that is called when a hover interaction starts.

onHoverEnd (e: HoverEvent) => void

Handler that is called when a hover interaction ends.

StyleProps
margin Responsive<Spacing | "auto">

The amount of margin applied to all edges of this component.

marginX Responsive<Spacing | "auto">

The amount of margin applied to the left and right edges of this component. Takes priority over margin.

marginY Responsive<Spacing | "auto">

The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.

marginTop Responsive<Spacing | "auto">

The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.

marginRight Responsive<Spacing | "auto">

The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.

marginBottom Responsive<Spacing | "auto">

The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.

marginLeft Responsive<Spacing | "auto">

The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

IconButton

Section titled “IconButton”

Displays an icon-only button that allows users to perform an action.

See button usage guidelines.

ref Ref<HTMLButtonElement>

The ref type for this component.

IconButtonProps
icon * ReactNode

The icon displayed on the button.

aria-label * string

The label describing the function of this button for assistive technologies.

variant 'primary' | 'secondary' | 'tertiary'

Determines the visual appearance of the button.

Defaults to 'secondary' .
tone 'base' | 'critical'

Determines the color tone of the button.

Defaults to 'base' .
size 'small' | 'medium' | 'large'

The size of the button.

Defaults to 'medium' .
fullWidth boolean

Whether the button should take up the whole available width.

Defaults to false .
isLoading boolean

Whether the button is in a loading state. This disables the button and replaces its contents with a spinner.

Defaults to false .
loadingLabel string

A string that identifies the loading state to assistive technologies. It will be announced by screen readers together with the button label. You must provide this prop if isLoading is true.

id string

The element's unique identifier. See MDN.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

UNSAFE_className string

Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.

UNSAFE_style CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

aria-labelledby string

Identifies the element (or elements) that labels the current element.

aria-describedby string

Identifies the element (or elements) that describes the object.

aria-details string

Identifies the element (or elements) that provide a detailed, extended description for the object.

isDisabled boolean

Whether the button is disabled.

type 'button' | 'reset' | 'submit'

The behavior of the button when used in an HTML form.

Defaults to 'button' .
onHoverStart (e: HoverEvent) => void

Handler that is called when a hover interaction starts.

onHoverEnd (e: HoverEvent) => void

Handler that is called when a hover interaction ends.

onPress (e: PressEvent) => void

Handler that is called when the press is released over the target.

form string

The <form> element to associate the button with. The value of this attribute must be the id of a <form> in the same document.

name string

Submitted as a pair with the button's value as part of the form data.

value string

The value associated with the button's name when it's submitted with the form data.

StyleProps
margin Responsive<Spacing | "auto">

The amount of margin applied to all edges of this component.

marginX Responsive<Spacing | "auto">

The amount of margin applied to the left and right edges of this component. Takes priority over margin.

marginY Responsive<Spacing | "auto">

The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.

marginTop Responsive<Spacing | "auto">

The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.

marginRight Responsive<Spacing | "auto">

The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.

marginBottom Responsive<Spacing | "auto">

The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.

marginLeft Responsive<Spacing | "auto">

The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

IconLinkButton

Section titled “IconLinkButton”

Displays an icon-only button that allows users to navigate to another page or resource.

See button usage guidelines.

ref Ref<HTMLAnchorElement>

The ref type for this component.

IconLinkButtonProps
icon * ReactNode

The icon displayed on the button.

aria-label * string

The label describing the function of this button for assistive technologies.

href * string

A URL to link to.

variant 'primary' | 'secondary' | 'tertiary'

Determines the visual appearance of the button.

Defaults to 'secondary' .
tone 'base' | 'critical'

Determines the color tone of the button.

Defaults to 'base' .
size 'small' | 'medium' | 'large'

The size of the button.

Defaults to 'medium' .
fullWidth boolean

Whether the button should take up the whole available width.

Defaults to false .
data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

UNSAFE_className string

Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.

UNSAFE_style CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

aria-labelledby string

Identifies the element (or elements) that labels the current element.

aria-describedby string

Identifies the element (or elements) that describes the object.

aria-details string

Identifies the element (or elements) that provide a detailed, extended description for the object.

routerOptions undefined

Options for the configured client side router.

isDisabled boolean

Whether the link is disabled.

hrefLang string

Hints at the human language of the linked URL. SeeMDN.

target HTMLAttributeAnchorTarget

The target window for the link. See MDN.

rel string

The relationship between the linked resource and the current page. See MDN.

download string | boolean

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.

ping string

A space-separated list of URLs to ping when the link is followed. See MDN.

referrerPolicy HTMLAttributeReferrerPolicy

How much of the referrer to send when following the link. See MDN.

onHoverStart (e: HoverEvent) => void

Handler that is called when a hover interaction starts.

onHoverEnd (e: HoverEvent) => void

Handler that is called when a hover interaction ends.

StyleProps
margin Responsive<Spacing | "auto">

The amount of margin applied to all edges of this component.

marginX Responsive<Spacing | "auto">

The amount of margin applied to the left and right edges of this component. Takes priority over margin.

marginY Responsive<Spacing | "auto">

The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.

marginTop Responsive<Spacing | "auto">

The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.

marginRight Responsive<Spacing | "auto">

The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.

marginBottom Responsive<Spacing | "auto">

The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.

marginLeft Responsive<Spacing | "auto">

The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.