User picker

Examples
Typescript ❤️

Fabric component for display a dropdown to select a user from

Install
yarn add @atlaskit/user-picker
npm
@atlaskit/user-picker
Source
Bitbucket
Bundle
unpkg.com
Changelog
Latest

11.0.4

Patch Changes

  • #119746 e669148287cf3 - Internal refactor for compatibility with the latest version of @atlaskit/avatar. The UI remains consistent.
  • Updated dependencies

Note: This component is designed for internal Atlassian development.

External contributors will be able to use this component but will not be able to submit issues.

This is the platform field for selecting users. On top of that you can also select Teams. This package provides two different modes of selection: single and multi user/team picker.

DISCLAIMER:

Please consider using the smart-user-picker over user-picker if possible. This encourages consistency and monitoring. If you cannot use smart-user-picker, please reach out to the our slack channels, #search-plex, so that we can work with you.

Usage

Import the component in your React app as follows:

import UserPicker from '@atlaskit/user-picker';

Single User Picker

Enter people or teams...

Multi User Picker

Enter people or teams...

Watchers

Enter people or teams...

User Picker Props

fieldId union required

  • Used to configure additional information regarding where the
  • user picker has been mounted.
  • The purpose is to give more context as to where user picker events
  • are being fired from, as the current data may not uniquely identify
  • which field is the source.
  • The value will be passed as a data attribute for analytics.
  • Examples include "assignee", "watchers" and "share".
  • A second usage for the fieldId is for server side rendering (SSR) where it must be a unique id per UserPicker
  • instance contained in the serialized SSR content. E.g. a SPA page rendered through SSR that has multiple user pickers.
  • fieldId can be set to null if the integrator is not listening
  • for the analytic events or does not care about SSR.
One of
string,
null

options arrayType

List of users or teams to be used as options by the user picker.

Array
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean

width union = 350

Width of the user picker field. It can be the amount of pixels as numbers or a string with the percentage.

One of
number,
string

menuMinWidth number

Sets the minimum width for the menu. If not set, menu will always have the same width of the field.

maxPickerHeight number

Sets max height of the user picker. If not set, the height will grow based on number of picked users.

textFieldBackgroundColor boolean

Sets the background color to be the same color as a textfield (Atlaskit N10)

loadOptions object

Function used to load options asynchronously. accepts two optional params: searchText?: optional text to filter results sessionId?: user picker session identifier, used to track success metric for users providers

string function required function
searchText,
sessionId
=> One of
T | PromiseLike<T>One of
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
,
Array
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
,
IterableOne of
T | PromiseLike<T>One of
Array
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
,
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
,
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
,
Array
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean

loadOptionsErrorMessage function

Function to generate the error message when there's a failure executing the loadOptions prop. If not provided, will default to a default error message.

value => React.ReactNode

loadUserSource object

Function used to load user source if they are an external user. accepts two params: accountId: account ID of the user to lookup sources signal: AbortController signal to abort the request if the tooltip is closed

string function required function
accountId,
signal
=> PromiseArray
sourceId string required
sourceType required One of
"google",
"slack",
"microsoft",
"jira",
"confluence",
"other-atlassian"

onChange function

Callback for value change events fired whenever a selection is inserted or removed.

function
value,
action
=> undefined

isMulti boolean = false

To enable multi user picker.

anchor React.ComponentType<any>

Anchor for the user picker popup.

React.ComponentTypeany

open boolean

Controls if user picker menu is open or not. If not provided, UserPicker will control menu state internally.

isLoading boolean

Show the loading indicator.

onInputChange function

Callback for search input text change events.

function
query,
sessionId
=> undefined

onSelection function

Callback for when a selection is made.

function
value,
sessionId,
baseUserPicker
=> undefined

onFocus function

Callback for when the field gains focus.

sessionId => undefined

onBlur function

Callback for when the field loses focus.

sessionId => undefined

onClear function

Callback for when the value/s in the picker is cleared.

sessionId => undefined

onOpen function

Callback that is triggered when popup picker is opened

sessionId => undefined

onClose function

Callback that is triggered when popup picker is closed

sessionId => undefined

onKeyDown function

Callback that is trigger on key down in text input

event => undefined

appearance union

Appearance of the user picker.

One of
"normal",
"compact"

subtle boolean

Display the picker with a subtle style.

noBorder boolean

Display the picker with no border.

styles import

You may pass through a StylesConfig to be merged with the picker default styles if a custom override is required. Consider using noBorder, subtle before customising further. See https://react-select.com/styles

@atlaskit/select.StylesConfig

defaultValue union

Default value for the field to be used on initial render. defaultValue differs from value in that it sets the initial value then leaves the component 'uncontrolled' whereas setting the value prop delegates responsibility for maintaining the value to the caller (i.e. listen to onChange)

One of
One of
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
,
Array
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
,
null,
undefined
,
Pick
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
, One of
"id",
"type",
"isDisabled"
,
Array
Pick
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
, One of
"id",
"type",
"isDisabled"

placeholder React.ReactNode

Placeholder text to be shown when there is no value in the field.

React.ReactNode

placeholderAvatar union

Placeholder avatar style - defaults to person

One of
"person",
"team"

addMoreMessage string

Message to encourage the user to add more items to user picker.

noOptionsMessage union

Message to be shown when the menu is open but no options are provided. If message is null, no message will be displayed. If message is undefined, default message will be displayed.

One of
value => One of
string,
null,
React.ReactNode
,
null,
React.ReactNode

value union

Controls if the user picker has a value or not. If not provided, UserPicker will control the value internally.

One of
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
,
Array
avatarUrl any
fixed boolean
id string required
isDisabled boolean
lozenge union One of
string,
text string required
tooltip string
appearance One of
"default",
"success",
"removed",
"inprogress",
"new",
"moved"
isBold boolean
,
react.ReactNode
name string required
type union One of
"user",
"team",
"email",
"group",
"custom",
"external_user"
tooltip string
title string
verified boolean
,
null,
undefined

isDisabled boolean

Disable all interactions with the picker, putting it in a read-only state.

isInvalid boolean

Display the picker with a style to show the value is invalid

isClearable boolean

Display a remove button on the single picker. True by default.

clearValueLabel string

Optional tooltip to display on hover over the clear indicator.

menuPosition union

React-select prop for controlling menu position

One of
"absolute",
"fixed"

captureMenuScroll boolean

React-select prop for blocking menu scroll on container when menu scrolled to the very top/bottom of the menu

menuPortalTarget HTMLElement

Whether the menu should use a portal, and where it should attach.

HTMLElement

allowEmail boolean

Whether the user is allowed to enter emails as a value.

suggestEmailsForDomain string

Setting this with allowEmail will cause the picker to constantly show an email option at the bottom for the supplied email domain/an email the user types in

emailLabel string

Email option label

disableInput boolean

Whether to disable interaction with the input

isValidEmail function

Override default email validation function.

inputText => One of
"INVALID",
"POTENTIAL",
"VALID"

autoFocus boolean

Override the internal behaviour to automatically focus the control when the picker is open

maxOptions number

The maximum number options to be displayed in the dropdown menu during any state of search. The value should be non-negative.

inputId string

Allows clicking on a label with the same id to open user picker.

closeMenuOnScroll union

Whether to close menu on scroll

One of
boolean,
EventListener

menuShouldBlockScroll boolean

Whether to block scrolling actions

ariaLabel string

Accessibility: Uses to set aria-label of the input

ariaLabelledBy string

Accessibility: Identifies the element (or elements) that labels the current element.

ariaDescribedBy string

Accessibility: Identifies the element (or elements) that describe the current element.

ariaLive union

Accessibility: Used to set the priority with which screen reader should treat updates to live regions.

One of
"polite",
"off",
"assertive"

name string

Name to use for input element.

header React.ReactNode

Header to be displayed in MenuList

React.ReactNode

required boolean

Accessibility: A field to dictate if this is a mandatory field in the form.

UNSAFE_hasDraggableParentComponent boolean

Enables workaround for when is nested inside from react-beautiful-dnd This relationship prevents the dropdown menu from opening because of bugs in the default focus state and clicking in a particular area of Context: https://hello.atlassian.net/wiki/spaces/~989411314/pages/2861097485/Investigation+Notes+for+atlaskit+select+react-beautiful-dnd#Temporary-Solution

openMenuOnClick boolean

Override the internal behaviour of default menu open on focus and applicable for single value select