Props
Localization
Be sure to localize text
and accessibilityLabel
. Note that localization can lengthen text by 20 to 30 percent. Avoid truncating ButtonLink text whenever possible. Refer to the ButtonLink usage guidelines for more information.
Usage guidelines
- Communicating a navigation that will occur.
- Triggering or enabling a navigation, such as visiting another URL.
- Progressing or regressing a user through a step in a flow in separate URLs.
- Inlined in text. Instead, use Link.
- Limited space available. Consider using an IconButtonLink instead.
Best practices
Place primary ButtonLinks to the right or top of other ButtonLink styles.
Place more than one primary ButtonLink per container/area.
Show the full text on ButtonLinks. ButtonLinks should be stacked when they cannot be displayed side by side.
Truncate the ButtonLink text. In rare instances where ButtonLinks must remain on one line, truncate the text on the secondary ButtonLink before truncating on the primary ButtonLink.
Use an IconButton + Tooltip next to the disabled ButtonLink if you need to explain why it is disabled.
Use a Tooltip on disabled ButtonLink, as it is not accessible for keyboard and screen reader users.
Accessibility
Variants
External handlers
ButtonLink consumes external handlers from GlobalEventsHandlerProvider.
Handlers:
- onNavigation: executed when ButtonLink is clicked
See GlobalEventsHandlerProvider for more information.
Icons
iconEnd
adds an icon after the ButtonLink text. Icons should only be used to visually reinforce a specific function or interaction of the ButtonLink. Menus and external links are a common use case. The icon visit
is recommended for use with ButtonLink. Note that iconEnd on ButtonLink is not accessible to screen readers.
import { ButtonLink, Flex } from 'gestalt'; export default function Example() { return ( <Flex alignItems="center" height="100%" justifyContent="center" width="100%" > <ButtonLink accessibilityLabel="" iconEnd="visit" size="lg" text="Visit Pinterest" href="https://www.pinterest.com/" /> </Flex> ); }
States
- Default
The typical state of a ButtonLink that represents it can be interacted with and is not in a selected state. - Disabled
Used to block user interaction such as hover, focus and click. Disabled Buttons are completely unreachable by a keyboard and screenreader, so do not attach Tooltips to disabled Buttons.
import { ButtonLink, Flex } from 'gestalt'; export default function Example() { return ( <Flex alignItems="center" height="100%" justifyContent="center" width="100%" > <ButtonLink accessibilityLabel="Visit Pinterest" color="red" text="Visit Pinterest" size="lg" href="https://www.pinterest.com/" /> </Flex> ); }
import { ButtonLink, Flex } from 'gestalt'; export default function Example() { return ( <Flex alignItems="center" height="100%" justifyContent="center" width="100%" > <ButtonLink accessibilityLabel="Go back" disabled text="Go back" size="lg" href="https://www.pinterest.com/" /> </Flex> ); }
rel and target
These optional props control the behavior of ButtonLink. External links commonly use target="_blank"
to open the link in a new tab or window, and rel="nofollow"
to provide hints for SEO.
import { ButtonLink, Flex } from 'gestalt'; export default function Example() { return ( <Flex alignItems="center" height="100%" justifyContent="center" width="100%" > <ButtonLink accessibilityLabel="Visit Pinterest" iconEnd="visit" size="lg" text="Visit Pinterest" rel="nofollow" target="blank" href="#" /> </Flex> ); }
Component quality checklist
Quality item | Status | Status description |
---|---|---|
Figma Library | Component is not currently available in Figma. | |
Responsive Web | Ready | Component responds to changing viewport sizes in web and mobile web. |
Related
Button
Use Button when an action is needed instead of a link.
ButtonGroup
When displaying multiple ButtonLinks in a layout, use ButtonGroup to ensure consistent spacing and wrapping behavior.
IconButton
Use IconButton when only an icon is needed instead of text.
TapArea
Use TapArea to make non-button elements interactive, like an Image. This ensures the element interaction is accessible and uses Gestalt styles.
Tabs
Tabs are intended for page-level navigation between multiple URLs.
GlobalEventsHandlerProvider
GlobalEventsHandlerProvider allows external link navigation control across all children components with link behavior.
See GlobalEventsHandlerProvider to learn more about link navigation.