For Developers

Combobox

Combobox is an abstract compound component - it should not be used on its own, but used as a base to create combobox components. The Combobox system provides components, models, loaders, and elemProps hooks.

The term "Combobox" is based on the Combobox Pattern as defined in the ARIA Authoring Practices Guide (APG):

A combobox is an input widget with an associated popup that enables users to select a value for the combobox from a collection of possible values.

Examples of a "combobox" would be date pickers, autocomplete, and select components.

Examples

Autocomplete

This example shows an Autocomplete example using FormField, InputGroup, and the Combobox components to make an autocomplete form field. It uses useComboboxLoader to make mock API calls using setTimeout. Your application may use fetch, WebSockets, or other means of communicating with a server.

Fruit

Component API

Combobox

Props

Props extend from . If a model is passed, props from ComboboxModelConfig are ignored.

Name	Type	Description
`children`	`ReactNode`	Children of the `Combobox`. Should contain a `Combobox.Input` and a `Combobox.Menu`
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

Combobox.Input

The input of the Combobox. This element will have role="combobox" applied, along with aria-haspopup="true"

Props

Props extend from . Changing the as prop will change the element interface.

Name	Type	Description
`error`		The type of error associated with the TextInput (if applicable).
`width`	`number \| string`	The width of the TextInput.
`theme`
`grow`	`boolean`	True if the component should grow to its container's width. False otherwise.
`children`	`React.ReactNode`
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.
`ref`	`React.Ref<R = >`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

useComboboxInput

useComboboxInput Adds all attributes necessary to start with a . It opens the menu with arrow keys, uses , and handles keyboard arrows to navigate items of the menu. You may also compose this hook to add more specific behaviors for your .

(
  (
    model: , 
    elemProps: {}, 
    ref: React.Ref
  ) => {
    onKeyDown: (event: ) => void;
    onBlur: (event: ) => void;
    onChange: (event: <>) => void;
    onClick: (event: ) => void;
    value:  string  | undefined;
    role: 'combobox';
    aria-haspopup: true;
    aria-expanded: boolean;
    aria-autocomplete: 'list';
    aria-controls: any;
    aria-activedescendant:  null  | undefined;
    id: string;
    ref: (instance:    | null) => void;
  }, 
  , 
  , 
  , 
  , 
  
)

A custom component that uses aria-activedescendant instead of roving tab index to keep the focus on the .

Name	Type	Description
`children`	`ReactNode`	Children of the .
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

Combobox.Menu.Popper

The "Popper" of a . The popper will appear around the . It renders a div element that is portalled to the document.body which is controlled by the . The PopupStack is not part of React. This means no extra props given to this component will be forwarded to the div element, but the ref will be forwarded. Also fallback placements for the popper with be either top or bottom.

Props extend from div. Changing the as prop will change the element interface.

Name	Type	Description	Default
`anchorElement`	`<Element> \| Element \| null`	The reference element used to position the Popper. Popper content will try to follow the `anchorElement` if it moves and will reposition itself if there is no longer room in the window.
`children`	`((props: { placement: ; }) => ReactNode) \| ReactNode`	The content of the Popper. If a function is provided, it will be treated as a Render Prop and pass the `placement` chosen by PopperJS. This `placement` value is useful if your popup needs to animate and that animation depends on the direction of the content in relation to the `anchorElement`.
`getAnchorClientRect`	`() =>`	When provided, this optional callback will be used to determine positioning for the Popper element instead of calling `getBoundingClientRect` on the `anchorElement` prop. Use this when you need complete control over positioning. When this prop is specified, it is safe to pass `null` into the `anchorElement` prop. If `null` is passed into the `anchorElement` prop, an `owner` will not be provided for the `PopupStack`.
`open`	`boolean`	Determines if `Popper` content should be rendered. The content only exists in the DOM when `open` is `true`	`true`
`placement`		The placement of the `Popper` contents relative to the `anchorElement`. Accepts `auto`, `top`, `right`, `bottom`, or `left`. Each placement can also be modified using any of the following variations: `-start` or `-end`.
`fallbackPlacements`	`[]`	Define fallback placements by providing a list of in array (in order of preference). The default preference is following the order of `top`, `right`, `bottom`, and `left`. Once the initial and opposite placements are not available, the fallback placements will be in use. Use an empty array to disable the fallback placements.
`onPlacementChange`	`(placement: ) => void`	A callback function that will be called whenever PopperJS chooses a placement that is different from the provided `placement` preference. If a `placement` preference doesn't fit, PopperJS will choose a new one and call this callback.
`popperOptions`	`<PopperOptions>`	The additional options passed to the Popper's `popper.js` instance.
`portal`	`boolean`	If false, render the Popper within the DOM hierarchy of its parent. A non-portal Popper will constrained by the parent container overflows. If you set this to `false`, you may experience issues where you content gets cut off by scrollbars or `overflow: hidden`	`true`
`popperInstanceRef`	`Ref<>`	Reference to the PopperJS instance. Useful for making direct method calls on the popper instance like `update`.
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`div`
`ref`	`React.Ref<R = div>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

usePopupPopper

Adds the necessary props to a component. Used by the subcomponent.

(
  model: , 
  elemProps: {}, 
  ref: React.Ref
) => {
  open: boolean;
  anchorElement: <>;
  ref: (instance:    | null) => void;
  onPlacementChange: (placement: ) => void;
}

Combobox.Menu.List

The combobox menu list follows the Collections API. A list can either contain static items or a render prop and items to the model.

const MyComponent = () => {
  const model = useComboboxModel({
    items: ['First Item', 'Second Item']
  })

  return (
    <Combobox model={model}>
      // other combobox subcomponents
      <Combobox.Menu.List>
        {(item) => <Combobox.Menu.Item>{item}</Combobox.Menu.Item>}
      </Combobox.Menu.List>
    </Combobox>
  )
}

Combobox.Menu.List supports all props from thelayout component.

Props extend from ul. Changing the as prop will change the element interface.

Name	Type	Description	Default
`children`	`ReactNode \| (( item: T, index: number ) => ReactNode)`
`cs`		The `cs` prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using `cs`, you can merge that prop in as well. Any style that is passed to the `cs` prop will override style props. If you wish to have styles that are overridden by the `css` prop, or styles added via the `styled` API, use wherever `elemProps` is used. If your component needs to also handle style props, use instead. import {handleCsProp} from '@workday/canvas-kit-styling'; import {mergeStyles} from '@workday/canvas-kit-react/layout'; // ... // `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same // function signature, but adds support for style props. return ( <Element {...handleCsProp(elemProps, [ myStyles, myModifiers({ size: 'medium' }), myVars({ backgroundColor: 'red' }) ])} > {children} </Element> )
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`ul`
`ref`	`React.Ref<R = ul>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

useComboboxMenuList

The listbox uses aria-labelledby pointing to the . This input should be labelled by a form field label for proper accessibility. Use to ensure proper accessibility.

(
  model: , 
  elemProps: {}, 
  ref: React.Ref
) => {
  role: 'listbox';
  aria-labelledby: string;
  id: any;
  flexDirection:  'column'  | 'row';
}

Combobox.Menu.Item

Combobox.Menu.Item has an optional data-id prop that identifies the item in the Combobox.Menu.List and will be passed to the optional onSelect callback of the ComboboxModel. Combobox.Menu.Item can contain any HTML.

Props extend from li. Changing the as prop will change the element interface.

Name	Type	Description	Default
`children`	`ReactNode`
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`li`
`ref`	`React.Ref<R = li>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

useComboboxMenuItem

This hook sets up accessibility and behavior of a component. It prevents focus when clicking so the focus stays on the component and selects an item when the user clicks on it. It also prevents items with an aria-disabled attribute from being selected. A focus CSS class is added when the item has "focus" (when the cursor is on the item).

(
  (
    model: , 
    elemProps: {
      data-id: string;
    }, 
    ref: React.Ref
  ) => {
    role: 'option';
    aria-selected:  true  | undefined;
    onMouseDown: (event: <>) => void;
    className:  ''  | 'focus';
  }, 
  , 
  
)

Combobox.Menu.Card

Combobox.Menu.Card is a non-semantic element used to give the dropdown menu its distinct visual cue that the dropdown menu is floating above other content. Combobox.Menu.Card usually contains a Combobox.Menu.List, but it can also contain other elements like a header or footer.

Combobox.Menu.Card supports all props from thelayout component.

Props extend from div. Changing the as prop will change the element interface.

Name	Type	Description	Default
`children`	`ReactNode`	Children of the Card. Should contain a `<Card.Body>` and an optional `<Card.Heading>`
`cs`		The `cs` prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using `cs`, you can merge that prop in as well. Any style that is passed to the `cs` prop will override style props. If you wish to have styles that are overridden by the `css` prop, or styles added via the `styled` API, use wherever `elemProps` is used. If your component needs to also handle style props, use instead. import {handleCsProp} from '@workday/canvas-kit-styling'; import {mergeStyles} from '@workday/canvas-kit-react/layout'; // ... // `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same // function signature, but adds support for style props. return ( <Element {...handleCsProp(elemProps, [ myStyles, myModifiers({ size: 'medium' }), myVars({ backgroundColor: 'red' }) ])} > {children} </Element> )
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`div`
`ref`	`React.Ref<R = div>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

useComboboxCard

This hook sets the minWidth style attribute to match the width of the component.

(
  model: , 
  elemProps: {}, 
  ref: React.Ref
) => {
  minWidth: number;
}

Model

useComboboxModel

ComboboxModel extends the and the . Selecting items from the menu will dispatch an input event on the input which should work with form libraries, automation, and autofill.

const model = useComboboxModel()

<Combobox model={model}>{Combobox child components}</Combobox>

useComboboxModel (config: ):

Hooks

useComboboxLoader

Creates a Combobox data loader and a model. The Combobox loader extends the and connects a to the filter of the data loader. A simple loader using fetch could look like the following:

const {model, loader} = useComboboxLoader(
  {
    total: 0,
    pageSize: 20,
    async load({pageNumber, pageSize, filter}) {
      // `filter` will be a `string`
      return fetch(`/myUrl?filter=${filter}`)
        .then(response => response.json())
        .then(response => {
          return {total: response.total, items: response.items};
        });
    },
  },
  useComboboxModel
);

Can't Find What You Need?

Check out our FAQ section which may help you find the information you're looking for.

FAQ Section

For Developers

Combobox

Examples

Autocomplete

Component API

Combobox

Props

Combobox.Input

Props

useComboboxInput

Combobox.Menu

Props

Combobox.Menu.Popper

Props

usePopupPopper

Combobox.Menu.List

Layout Component

Props

useComboboxMenuList

Combobox.Menu.Item

Props

useComboboxMenuItem

Combobox.Menu.Card

Layout Component

Props

useComboboxCard

Model

useComboboxModel

Hooks

useComboboxLoader

Can't Find What You Need?