ButtonLink
- Library
- UDS Base
- Repository
- github.com/telus/universal-design-system
- Package
- npmjs.com/package/@telus-uds/ds-allium
- Package version
- 1.14.0
Introduction
import { ButtonLink } from '@telus-uds/ds-allium'
ButtonLink is a component with the visual appearance of a button but the semantics and behaviour of a link.
Guidance
Use ButtonLink where a user is making a choice to advance an action, and acting on that choice takes the user to another page.
Alternatives
Do not use ButtonLink for:
- A single navigation action that is the only logical next step (or is a step back): consider ChevronLink
- Actions that occur immediately on press on the current page: consider Button
- Actions that occur within the current page or screen; consider TextButton
- General links that are outside of the current action flow: consider Link
Accessibility
Insert A11yText any time an interactive element's label lacks context that a sighted user would see in the content around it. Many users of assistive technology explore a page by cycling through the interactive elements first.
ButtonLink is treated as a navigational link by accessibility tools. It accepts
React Native's accessibility props (web docs,
native docs).
Platform considerations
The component is available on both native platforms and web.
On web, ButtonLink will render as an <a> anchor link if a href is provided, allowing for
common link actions such as open in new tab.
On native apps, links to web addresses will be opened according to the user's device's link handling behaviour: usually opening the user's default browser (or choice of browsers) with a back action to return to the app.
Props
| Name | Type | Default | Description |
|---|---|---|---|
| children | ABBPropTypes .childrenOf( PropTypes.oneOfType([ABBPropTypes.elementType(A11yText), PropTypes.string]) ) | Button's children must be either: - One or more text strings and / or A11yText components - A render function with contents that responds to current button state by being passed an object of: ''' { hovered<bool>, focused<bool>, pressed<bool>, inactive<bool>, selected<bool>, textStyles<RNStyle> } ''' | |
| disabled | bool | Alias for 'inactive' | |
| href | string | ||
| hrefAttrs | { download: string, rel: string, target: enum } | ||
| inactive | bool | If true, prevents the button from being pressed, changes the cursor (on web) and accessibility attributes to communicate this to the user, and applies 'inactive: true' appearances from the theme | |
| onPress | func | Function called when the button is pressed. Required unless the button has a href. | |
| onPressIn | func | ||
| onPressOut | func | ||
| tokens | custom | System tokens prop, see tokens for more details | |
| variant | objectOf | System variant prop, see variants for more details |
Note: this component also handles all React Native accessibility props
Tokens
In exceptional circumstances, the following tokens can be passed to this component to override its default styles. Do not do this unless absolutely necessary. Read more about overriding styles.
View Tokens
| Prop Name | Token Property | Token Type |
|---|---|---|
| tokens | borderColor | color |
| borderWidth | border | |
| borderRadius | radius | |
| shadow | shadow | |
| fontSize | fontSize | |
| color | color | |
| lineHeight | lineHeight | |
| textAlign | flexJustifyContent | |
| alignSelf | flexAlign | |
| fontName | fontName | |
| fontWeight | fontWeight | |
| backgroundColor | color | |
| opacity | opacity | |
| paddingLeft | size | |
| paddingRight | size | |
| paddingTop | size | |
| paddingBottom | size | |
| width | size | |
| minWidth | size | |
| outerBorderColor | color | |
| outerBorderWidth | border | |
| outerBorderGap | size | |
| outerBackgroundColor | color |
Figma
Variants
ButtonLink's variants are the same as for Button.
Feedback
- Spotted a problem with this component? Raise an issue on GitHub
- See any existing issues for this component
- Contact the team on slack in #ds-allium-support