Search

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

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

Package version

1.14.0

Loading...

<Search />

<Search />

Introduction

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

Use Search for text-based searching or filtering with optional autocomplete functionality.

Guidance

Search includes a clear button, which will appear as text is entered and pressing it will cause the input's internal state value to be set to an empty string.

Updating parent on changes

Use the onChange prop to react to value changes and the onSubmit prop to react on search submission.

Loading...

function SearchWithCallbacks() { const [value, setValue] = useState('') const [submitted, setSubmitted] = useState() return ( <StackView space={2}> <Search onChange={setValue} onSubmit={setSubmitted} /> <Typography> Current value is: <Typography variant={{ bold: true }}>{value}</Typography> </Typography> <Typography> Submitted value was: <Typography variant={{ bold: true }}>{submitted}</Typography> </Typography> </StackView> ) }

function SearchWithCallbacks() {
  const [value, setValue] = useState('')
  const [submitted, setSubmitted] = useState()

  return (
    <StackView space={2}>
      <Search onChange={setValue} onSubmit={setSubmitted} />

      <Typography>
        Current value is: <Typography variant={{ bold: true }}>{value}</Typography>
      </Typography>
      <Typography>
        Submitted value was: <Typography variant={{ bold: true }}>{submitted}</Typography>
      </Typography>
    </StackView>
  )
}

Controlled usage

Pass value and onChange to control the search input from a parent.

caution

Allium-branded autocomplete suggestions for Search are still under design consideration.

The below example is only an example of the capabilities of Search props, and not an example of how such a feature should look or behave.

Please contact DPA for advice on design, user experience and accessibility of similar features.

Accessibility

Use the copy prop to select english or french copy for the accessibility labels. You may also pass in a custom dictionary object.

Platform considerations

The component is available on both native platforms and web.

Props

Name	Type	Default	Description
accessibilityLabel	string		Use to provide an accessible label for the input (visually hidden).
copy	'en' | 'fr' | { accessibilityLabel: string, clearButtonAccessibilityLabel: string, submitButtonAccessibilityLabel: string }	'en'	Select English or French copy for the accessible labels. You may also pass in a custom dictionary object.
inactive	bool		Disables all user interactions with the search input.
initialValue	string		Use this to set the initial value of the search input. Updating 'initialValue' will **not** update the actual value.
onChange	func		Use to react upon search input's value changes. Will receive the searched value as an argument.
onClear	func		Triggered when the clear button is pressed.
onFocus	func		Triggered when the search input is focused.
onSubmit	func		Triggered when the search input is submitted, either by pressing the submit button, "Enter" key on web, or "Search" key in a mobile keyboard.
placeholder	string		Label rendered in the search input when it has no value.
tokens	custom		System tokens prop, see tokens for more details
variant	objectOf		System variant prop, see variants for more details

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	backgroundColor	color
	color	color
	borderWidth	border
	borderColor	color
	borderRadius	radius
	paddingTop	size
	paddingBottom	size
	paddingLeft	size
	paddingRight	size
	outerBackgroundColor	color
	outerBorderWidth	border
	outerBorderColor	color
	outerBorderRadius	radius
	fontName	fontName
	fontWeight	fontWeight
	fontSize	fontSize
	lineHeight	lineHeight
	placeholderColor	color
	buttonsGap	size
	clearButtonIcon	icon
	submitButtonIcon	icon

Figma

Variants

This component has no visual variants but its appearance may change based on the inactive prop:

Loading...

<Search inactive />

<Search inactive />

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