Button

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/ds-allium

Package version

1.14.0

Loading...

<Button onPress={() => alert('Hello world!')}>Click me</Button>

<Button onPress={() => alert('Hello world!')}>Click me</Button>

Introduction

import { Button } from '@telus-uds/ds-allium'

Buttons allow users to perform an action.

They have multiple styles for various needs, and are ideal for calling attention to where a user needs to do something in order to move forward in a flow.

Guidance

Provide a function as the onPress prop to perform an action when clicked.

• Use buttons to move through a transaction
• Aim to use only one primary button variant per page
• Keep the text short and precise. It should fit on a single line (our recommendation is 2-24 characters for French and English)
• Make sure the button text describes an action
• Buttons should not be disabled. Use inline (on blur) error messaging, to provide feedback when the form is invalid

Alternatives

Do not use Button for:

• Navigating to a URL which represents a choice in the current action flow: consider ButtonLink
• One navigation action taking the user to a page that is the only logical next step: consider ChevronLink
• Smaller actions that occur within the current page or screen: consider TextButton
• Navigating to a page outside of the user's current action flow: consider Link

Using refs

Button component provides ref forwarding, which allows the user to trigger events like focusing, clicking, etc., programmatically:

Loading...

function buttonRefExample() { const ref = useRef() const handlePress = () => ref.current.focus() return ( <StackView> <Typography>Click THIS to focus on THAT</Typography> <Button onPress={handlePress}>THIS</Button> <Button ref={ref}>THAT</Button> </StackView> ) }

function buttonRefExample() {
  const ref = useRef()
  const handlePress = () => ref.current.focus()

  return (
    <StackView>
      <Typography>Click THIS to focus on THAT</Typography>
      <Button onPress={handlePress}>THIS</Button>
      <Button ref={ref}>THAT</Button>
    </StackView>
  )
}

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.

Loading...

<StackView space={2}> <Typography>The new MegaPhone is our loudest phone yet.</Typography> <Button variant={{ priority: 'high' }} onPress={() => {}}> Add {<A11yText text="MegaPhone" />}to cart </Button> </StackView>

<StackView space={2}>
  <Typography>The new MegaPhone is our loudest phone yet.</Typography>
  <Button variant={{ priority: 'high' }} onPress={() => {}}>
    Add {<A11yText text="MegaPhone" />}to cart
  </Button>
</StackView>

Button is by default described to accessibility tools as having the button role. Button accepts React Native's accessibility props (web docs, native docs).

Platform considerations

The component is available on both native platforms and web.

Button background animated transitions are not currently supported in iOS or Android apps. Focus states are not well supported on native platforms.

Figma

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'
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.
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

Variants

Priority

• Priority indicates the importance of the call-to-action
• Limit the amount of high priority buttons on a page so that you proritize meaningful user flows

Loading...

<div style={{ display: 'flex', gap: '1em' }}> <Button onPress={noop} variant={{ priority: 'high' }}> High </Button> {/* default is low */} <Button onPress={noop} variant={{ priority: 'low' }}> Low </Button> </div>

<div style={{ display: 'flex', gap: '1em' }}>
  <Button onPress={noop} variant={{ priority: 'high' }}>
    High
  </Button>
  {/* default is low */}
  <Button onPress={noop} variant={{ priority: 'low' }}>
    Low
  </Button>
</div>

Danger

• Danger indicates a user action that is destructive that will result in loss of information or cause significant monetary charges
• Limit the use of the danger button whenever possible

Loading...

<Button onPress={noop} variant={{ danger: true }}> Danger </Button>

<Button onPress={noop} variant={{ danger: true }}>
  Danger
</Button>

Size

• Available in default or small size
• Size is not responsive, unless otherwise specified in code

Loading...

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}> <Button onPress={noop} variant={{ priority: 'high' }}> Regular </Button> <Button onPress={noop} variant={{ size: 'small', priority: 'high' }}> Small </Button> </div>

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
  <Button onPress={noop} variant={{ priority: 'high' }}>
    Regular
  </Button>
  <Button onPress={noop} variant={{ size: 'small', priority: 'high' }}>
    Small
  </Button>
</div>

Inverse

• Both high and low priority buttons are available in inverse
• Use inverse buttons on darker backgrounds

Loading...

<div style={{ display: 'flex', gap: '1em' }}> <Button onPress={noop} variant={{ priority: 'high', inverse: true }}> High </Button> <Button onPress={noop} variant={{ priority: 'low', inverse: true }}> Low </Button> </div>

<div style={{ display: 'flex', gap: '1em' }}>
  <Button onPress={noop} variant={{ priority: 'high', inverse: true }}>
    High
  </Button>
  <Button onPress={noop} variant={{ priority: 'low', inverse: true }}>
    Low
  </Button>
</div>

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