Button
The Button component allows users to initiate actions or submit forms with a single click
Use the LinkButton component instead when you need navigation functionality with a button-like appearance.
Installation
npm install --save @godaddy/antaresProps
The Button component accepts the following props:
variant?"primary" | "secondary" | "tertiary" | "critical" | "inline" | "minimal" | null | undefined—The variant of the button.
size?"sm" | "md" | null | undefined—The size of the button.
className?string | undefined—Additional class names to apply to the button.
children?React.ReactNode—The content of the button.
autoFocus?boolean | undefined—Whether the element should receive focus on render.
id?string | undefined—The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
style?StyleOrFunction<ButtonRenderProps> | undefined—The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
render?DOMRenderFunction<"button", ButtonRenderProps> | undefined—Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
slot?string | null | undefined—A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
onClick?((e: React.MouseEvent<FocusableElement>) => void) | undefined—**Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions.
isDisabled?boolean | undefined—Whether the button is disabled.
onPress?((e: PressEvent) => void) | undefined—Handler that is called when the press is released over the target.
onPressStart?((e: PressEvent) => void) | undefined—Handler that is called when a press interaction starts.
onPressEnd?((e: PressEvent) => void) | undefined—Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange?((isPressed: boolean) => void) | undefined—Handler that is called when the press state changes.
onPressUp?((e: PressEvent) => void) | undefined—Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
onFocus?((e: React.FocusEvent<Element, Element>) => void) | undefined—Handler that is called when the element receives focus.
onBlur?((e: React.FocusEvent<Element, Element>) => void) | undefined—Handler that is called when the element loses focus.
onFocusChange?((isFocused: boolean) => void) | undefined—Handler that is called when the element's focus status changes.
onKeyDown?((e: KeyboardEvent) => void) | undefined—Handler that is called when a key is pressed.
onKeyUp?((e: KeyboardEvent) => void) | undefined—Handler that is called when a key is released.
onHoverStart?((e: HoverEvent) => void) | undefined—Handler that is called when a hover interaction starts.
onHoverEnd?((e: HoverEvent) => void) | undefined—Handler that is called when a hover interaction ends.
onHoverChange?((isHovering: boolean) => void) | undefined—Handler that is called when the hover state changes.
type?"button" | "submit" | "reset" | undefined'button'The behavior of the button when used in an HTML form.
preventFocusOnPress?boolean | undefined—Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
form?string | undefined—The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#form).
formAction?string | ((formData: FormData) => void | Promise<void>) | undefined—The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner.
formEncType?string | undefined—Indicates how to encode the form data that is submitted.
formMethod?string | undefined—Indicates the HTTP method used to submit the form.
formNoValidate?boolean | undefined—Indicates that the form is not to be validated when it is submitted.
formTarget?string | undefined—Overrides the target attribute of the button's form owner.
name?string | undefined—Submitted as a pair with the button's value as part of the form data.
value?string | undefined—The value associated with the button's name when it's submitted with the form data.
excludeFromTabOrder?boolean | undefined—Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
The LinkButton component accepts the following props:
isExternal?boolean | undefined—Whether the link is external. It will show an external icon if true.
variant?"primary" | "secondary" | "tertiary" | "critical" | "inline" | "minimal" | null | undefined—The variant of the button.
size?"sm" | "md" | null | undefined—The size of the button.
className?string | undefined—Additional class names to apply to the button.
children?React.ReactNode—The content of the button.
autoFocus?boolean | undefined—Whether the element should receive focus on render.
id?string | undefined—The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
style?StyleOrFunction<LinkRenderProps> | undefined—The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
render?((props: React.DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> | React.DetailedHTMLProps<React.HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, renderProps: LinkRenderProps) => React.ReactElement) | undefined—Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Note: You can check if `'href' in props` in order to tell whether to render an `<a>` element. Requirements: - You must render the expected element type (e.g. if `<a>` is expected, you cannot render a `<button>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
slot?string | null | undefined—A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
onClick?((e: React.MouseEvent<FocusableElement>) => void) | undefined—**Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions.
isDisabled?boolean | undefined—Whether the link is disabled.
onPress?((e: PressEvent) => void) | undefined—Handler that is called when the press is released over the target.
onPressStart?((e: PressEvent) => void) | undefined—Handler that is called when a press interaction starts.
onPressEnd?((e: PressEvent) => void) | undefined—Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange?((isPressed: boolean) => void) | undefined—Handler that is called when the press state changes.
onPressUp?((e: PressEvent) => void) | undefined—Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
onFocus?((e: React.FocusEvent<Element, Element>) => void) | undefined—Handler that is called when the element receives focus.
onBlur?((e: React.FocusEvent<Element, Element>) => void) | undefined—Handler that is called when the element loses focus.
onFocusChange?((isFocused: boolean) => void) | undefined—Handler that is called when the element's focus status changes.
onKeyDown?((e: KeyboardEvent) => void) | undefined—Handler that is called when a key is pressed.
onKeyUp?((e: KeyboardEvent) => void) | undefined—Handler that is called when a key is released.
href?string | undefined—A URL to link to. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href).
hrefLang?string | undefined—Hints at the human language of the linked URL. See[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#hreflang).
target?React.HTMLAttributeAnchorTarget | undefined—The target window for the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
rel?string | undefined—The relationship between the linked resource and the current page. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel).
download?string | boolean | undefined—Causes the browser to download the linked URL. A string may be provided to suggest a file name. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download).
ping?string | undefined—A space-separated list of URLs to ping when the link is followed. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#ping).
referrerPolicy?React.HTMLAttributeReferrerPolicy | undefined—How much of the referrer to send when following the link. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy).
routerOptions?undefined—Options for the configured client side router.
onHoverStart?((e: HoverEvent) => void) | undefined—Handler that is called when a hover interaction starts.
onHoverEnd?((e: HoverEvent) => void) | undefined—Handler that is called when a hover interaction ends.
onHoverChange?((isHovering: boolean) => void) | undefined—Handler that is called when the hover state changes.
Examples
Basic Usage
The default/tertiary button is the base for all other buttons in the system. It provides no significant visual treatment other than to provide indication for the user to take a common action.
import { Button } from '@godaddy/antares';export function DefaultExample() { return <Button>Click me!</Button>;}Primary
The primary button should be used to indicate the most important action for the user to take in their current experience.
import { Button, type ButtonProps } from '@godaddy/antares';export function PrimaryExample(props: ButtonProps) { return ( <Button {...props} variant="primary"> Primary Button </Button> );}Secondary
The secondary button indicates an action of secondary importance.
import { Button } from '@godaddy/antares';export function SecondaryExample() { return <Button variant="secondary">Secondary Button</Button>;}Critical
The critical button signifies to the user a destructive action will take place.
import { Button } from '@godaddy/antares';export function CriticalExample() { return <Button variant="critical">Critical Button</Button>;}Inline
import { Button, Text } from '@godaddy/antares';export function InlineExample() { return ( <Text> I am an <Button variant="inline">inline button</Button> surrounded by text! </Text> );}Minimal
The minimal button is an icon-only button that's used when space is limited and/or when the action is universally understood.
Button Size | Gap Size | Example | Usage |
|---|---|---|---|
md | md | Recommended | |
md | sm | Can be used, but not recommended. | |
sm | md | Not recommended. The button may not be accessible at this size. | |
sm | sm | Not recommended. The button may not be accessible at this size. |
import { Button, Flex, Icon } from '@godaddy/antares';export function MinimalExample() { return ( <table className="button-story-table"> <thead> <tr> <th scope="col"> <Flex blockPadding="md" inlinePadding="md" gap="md"> Button Size </Flex> </th> <th scope="col"> <Flex blockPadding="md" inlinePadding="md" gap="md"> Gap Size </Flex> </th> <th scope="col"> <Flex blockPadding="md" inlinePadding="md" gap="md"> Example </Flex> </th> <th scope="col"> <Flex blockPadding="md" inlinePadding="md" gap="md"> Usage </Flex> </th> </tr> </thead> <tbody> <tr> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <code>md</code> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <code>md</code> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <Button variant="minimal" size="md" aria-label="Star"> <Icon icon="star" /> </Button> <Button variant="minimal" size="md" aria-label="Edit"> <Icon icon="edit" /> </Button> <Button variant="minimal" size="md" aria-label="More options" isDisabled> <Icon icon="ellipsis" /> </Button> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> Recommended </Flex> </td> </tr> <tr> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <code>md</code> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <code>sm</code> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="sm"> <Button variant="minimal" size="md" aria-label="Star"> <Icon icon="star" /> </Button> <Button variant="minimal" size="md" aria-label="Edit"> <Icon icon="edit" /> </Button> <Button variant="minimal" size="md" aria-label="More options" isDisabled> <Icon icon="ellipsis" /> </Button> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> Can be used, but not recommended. </Flex> </td> </tr> <tr> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <code>sm</code> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <code>md</code> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <Button variant="minimal" size="sm" aria-label="Star"> <Icon icon="star" /> </Button> <Button variant="minimal" size="sm" aria-label="Edit"> <Icon icon="edit" /> </Button> <Button variant="minimal" size="sm" aria-label="More options" isDisabled> <Icon icon="ellipsis" /> </Button> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> Not recommended. The button may not be accessible at this size. </Flex> </td> </tr> <tr> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <code>sm</code> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> <code>sm</code> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="sm"> <Button variant="minimal" size="sm" aria-label="Star"> <Icon icon="star" /> </Button> <Button variant="minimal" size="sm" aria-label="Edit"> <Icon icon="edit" /> </Button> <Button variant="minimal" size="sm" aria-label="More options" isDisabled> <Icon icon="ellipsis" /> </Button> </Flex> </td> <td> <Flex blockPadding="md" inlinePadding="md" gap="md"> Not recommended. The button may not be accessible at this size. </Flex> </td> </tr> </tbody> </table> );}Icon
You may provide an optional Icon element to the button. If you do not include text, you must provide an aria-label attribute to identify the purpose of the button. This will produce a square button.
import { Button, Flex, Icon, LinkButton, Text } from '@godaddy/antares';export function IconExample() { return ( <Flex direction="column" gap="md"> <div> <Button variant="primary"> <Icon icon="star" /> <Text>With an icon!</Text> </Button> </div> <div> <LinkButton variant="secondary" href="#" isExternal> <Text>An external link!</Text> </LinkButton> </div> <Flex alignItems="center" gap="sm"> <Text>Icon only button:</Text> <Button variant="primary" aria-label="Star"> <Icon icon="star" /> </Button> </Flex> <div> <Text> Hey look at me!{' '} <LinkButton href="#" variant="inline" isExternal> link button </LinkButton>{' '} I have an icon! </Text> </div> </Flex> );}Sizes
import { Button, Flex, Icon, LinkButton, Text } from '@godaddy/antares';export function SizesExample() { return ( <Flex alignItems="center" gap="sm" wrap="wrap"> <Button variant="primary" size="sm" aria-label="Star"> <Icon icon="star" /> </Button> <Button variant="primary" size="sm"> Small </Button> <LinkButton href="#" variant="primary" size="sm" aria-label="Star"> <Icon icon="star" /> <Text>Link Small</Text> </LinkButton> <Button variant="primary" aria-label="Star"> <Icon icon="star" /> </Button> <Button variant="primary">Medium</Button> <LinkButton href="#" variant="primary"> <Icon icon="star" /> <Text>Link Medium</Text> </LinkButton> </Flex> );}Disabled
import { Button, Flex, LinkButton } from '@godaddy/antares';export function DisabledExample() { return ( <Flex alignItems="center" gap="md" wrap="wrap"> <Button variant="primary" isDisabled> Primary Disabled </Button> <Button variant="secondary" isDisabled> Secondary Disabled </Button> <Button variant="tertiary" isDisabled> Tertiary Disabled </Button> <Button variant="critical" isDisabled> Critical Disabled </Button> <Button variant="inline" isDisabled> Inline Disabled </Button> <LinkButton variant="secondary" href="#" isDisabled> Link Disabled </LinkButton> </Flex> );}Alert
In-page alerts are non-intrusive notifications within a webpage, providing users with timely information or feedback without disrupting their experience.
Carousel
The Carousel component allows users to cycle through a series of content panels (typically images, cards, or text) in a horizontal or vertical layout. It is commonly used for featured content, product showcases, or testimonials.