Autosuggest#

The <Autosuggest> component is made up of two elements: a text input, and a popover list of items associated with the search input text.

This component is mainly used for typeaheads. If you wish to have the popover triggerable by a button, look at the SelectMenu component.

Import#

import { Autosuggest } from 'bumbag'

Usage#

Editable example

Labels#

Editable example
Editable example

Fields#

You can also use the <AutosuggestField> component, which internally has a FieldWrapper to wrap form controls such as labels, hint text and validation text.

It accepts a combination of Autosuggest props and FieldWrapper props.

Editable example

Automatic selection#

An autosuggest with automatic selection means that the highlighed element will be selected when the input is blurred.

Editable example

Restrict to options#

If the autosuggest is restricted to options, this means that the user can only pick an item from the list instead of typing their own value.

Editable example

Loading indicator#

You can render a loading indicator with the isLoading prop.

Editable example

Custom option component#

By supplying a component to the renderOption prop, you can render a customised option.

The renderOption prop also gives you:

  • a MatchedLabel component to render the matched text.
  • an option variable that contains of the option data.
Editable example

Custom empty text#

You can render custom empty text with the emptyText prop.

Editable example

Custom empty component#

You can render a custom empty component with the renderEmpty prop.

Editable example
Editable example

Option icons#

Editable example

Disabled#

Editable example

Disabled item#

Editable example

Fetching data (async)#

To fetch options asynchronously, pass an async function to the loadOptions prop (instead of passing an options prop).

The loadOptions function will give you the current input value, searchText, to perform your query.

Editable example

Pagination#

To turn on pagination for your autosuggest, set the pagination prop.

The loadOptions function will give you the current page to use in your query.

Editable example

Deferred#

By default, Bumbag will try and fetch the data when the component mounts, however, if you want to defer this, set the defer prop.

Editable example

Accessibility#

The <Autosuggest> component follows the WAI ARIA Combobox Pattern.

Patterns#

  • Autosuggest has a role of combobox.
  • The Autosuggest input field has a role of textbox.
  • The Autosuggest popover has a role of listbox.
  • The Autosuggest has an aria-owns value set to the ID of the popover.
  • The Autosuggest input field has an aria-controls value set to the ID of the popover.
  • DOM focus is maintained on the input field, while the assistive reader focus is moved within the popover with aria-activedescendant.

When focus is on the input field:

  • Focussing the input opens up the popover list of options.
  • Pressing will bring focus inside the popover, and focus the first option.
  • Pressing will bring focus inside the popover, and focus the last option.
  • Pressing Esc will dismiss the popover.
  • Clicking outside will dismiss the popover.
  • Pressing Enter accepts the current selection.

When focus is on an option inside the popover:

  • Pressing will focus the next available option.
  • Pressing will focus the previous available option.
  • Pressing Esc will dismiss the popover.
  • Clicking outside will dismiss the popover.

References#

Props#

Autosuggest Props#

automaticSelection boolean

Whether or not an Autosuggest option should be automatically selected.

cacheKey string

The key to cache the loadOptions results against.

containLabel boolean

If the label prop is supplied, is it contained inside the autosuggest?

defer boolean

Whether or not the invocation of loadOptions should be deferred until it the Autosuggest is opened.

disabled boolean

Indicates if the Autosuggest is disabled.

isLoading boolean

Indicates if the Autosuggest is loading.

label string

limit number

Applies a limit to the number of options that appear in the list.

loadOptions

(options: { page?: number; searchText?: string; variables?: any; }) => Promise<{ options: Options; }>

Supply an async function to loadOptions to load options from an external data source.

loadVariables { [key: string]: any; }

Supply variables (i.e. query parameters) to the loadOptions function.

options Option[]

Options to show in the list. If loadOptions is supplied, then you don't need to supply this.

onChange (Option: any) => void Required

Function to invoke when the option has been changed.

pagination boolean

Indicates if the list should be paginated. If true, then pagination will be applied to loadOptions.

popoverHeight string

Sets the height of the popover list.

placeholder string

Sets the placeholder of the search input.

restrictToOptions boolean

Restricts selection to the options supplied via options or loadOptions. Otherwise, it's free-for-all entry.

state string

Sets the visual state of the Autosuggest.

value { key?: ReactText; label?: string; value?: any; } Required

Sets the value of the Autosuggest. Must be in the shape of an option (i.e. { key: 1, label: 'Jake', value: 'legend' }).

variant string

errorText string

Sets the error text when the loadOptions function throws an error.

emptyText string

Sets the empty text when no options are present.

loadingText string

Sets the loading text when the options are loading.

loadingMoreText string

Sets the loading text when more options are loading (via pagination).

renderClearButton any

renderError any

renderEmpty any

renderLoading any

renderLoadingMore any

renderOption any

clearButtonProps

{
  unstable_system?: any;
  defaultChecked?: boolean;
  defaultValue?: string | number | string[];
  suppressContentEditableWarning?: boolean;
  suppressHydrationWarning?: boolean;
  accessKey?: string;
  ... 807 more ...;
  ignoreGrayOverride?: boolean;
}

inputProps

{
  unstable_system?: any;
  top?: string | number | {
    [key: string]: string
  }; right?: string | number | {
    [key: string]: string
  }; bottom?: string | number | {
    [key: string]: string
  }; left?: string | number | {
    [key: string]: string
  }; ... 809 more ...;
  onFocus?: (event: FocusEvent<...>) => void;
}

itemProps

{
  unstable_system?: any;
  defaultChecked?: boolean;
  defaultValue?: string | number | string[];
  suppressContentEditableWarning?: boolean;
  suppressHydrationWarning?: boolean;
  accessKey?: string;
  ... 816 more ...;
  isTabbable?: boolean;
}

popoverProps

{
  unstable_system?: any;
  defaultChecked?: boolean;
  defaultValue?: string | number | string[];
  suppressContentEditableWarning?: boolean;
  suppressHydrationWarning?: boolean;
  accessKey?: string;
  ... 817 more ...;
  isTabbable?: boolean;
}

dropdownMenuInitialState

{
  baseId?: string;
  unstable_virtual?: boolean;
  currentId?: string;
  orientation?: Orientation;
  wrap?: boolean | "horizontal" | "vertical";
  rtl?: boolean;
  loop?: boolean | "horizontal" | "vertical";
  ... 11 more ...;
  unstable_preventOverflow?: boolean;
}
Inherits Box props

use

string
  | (ComponentClass<any, any> & { useProps: any; })
  | (FunctionComponent<any> & { useProps: any; })

className string

children

string
  | number
  | boolean
  | {}
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<...>)>
  | ReactNodeArray
  | ReactPortal
  | ((props: BoxProps) => ReactNode)

alignX "right" | "left" | "center"

alignY "top" | "bottom" | "center"

colorMode string

overrides

{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 95 more ...;
  Template?: TemplateThemeConfig;
}

elementRef ((instance: any) => void) | RefObject<any>

themeKey string

AutosuggestField Props#

addonBefore

ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Addon component to the input (before). Similar to the addon components in Input.

addonAfter

ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Addon component to the input (after). Similar to the addon components in Input.

autosuggestProps

{
  unstable_system?: any;
  defaultChecked?: boolean;
  defaultValue?: string | number | string[];
  suppressContentEditableWarning?: boolean;
  suppressHydrationWarning?: boolean;
  accessKey?: string;
  ... 814 more ...;
  dropdownMenuInitialState?: Partial<...>;
}

Additional props for the Autosuggest component

orientation "horizontal" | "vertical"

If addonBefore or addonAfter exists, then the addons will render vertically.

Inherits Autosuggest props

automaticSelection boolean

Whether or not an Autosuggest option should be automatically selected.

cacheKey string

The key to cache the loadOptions results against.

containLabel boolean

If the label prop is supplied, is it contained inside the autosuggest?

defer boolean

Whether or not the invocation of loadOptions should be deferred until it the Autosuggest is opened.

disabled boolean

Indicates if the Autosuggest is disabled.

isLoading boolean

Indicates if the Autosuggest is loading.

label string

limit number

Applies a limit to the number of options that appear in the list.

loadOptions

(options: { page?: number; searchText?: string; variables?: any; }) => Promise<{ options: Options; }>

Supply an async function to loadOptions to load options from an external data source.

loadVariables { [key: string]: any; }

Supply variables (i.e. query parameters) to the loadOptions function.

options Option[]

Options to show in the list. If loadOptions is supplied, then you don't need to supply this.

onChange (Option: any) => void Required

Function to invoke when the option has been changed.

pagination boolean

Indicates if the list should be paginated. If true, then pagination will be applied to loadOptions.

popoverHeight string

Sets the height of the popover list.

placeholder string

Sets the placeholder of the search input.

restrictToOptions boolean

Restricts selection to the options supplied via options or loadOptions. Otherwise, it's free-for-all entry.

state string

Sets the visual state of the Autosuggest.

value { key?: ReactText; label?: string; value?: any; } Required

Sets the value of the Autosuggest. Must be in the shape of an option (i.e. { key: 1, label: 'Jake', value: 'legend' }).

variant string

errorText string

Sets the error text when the loadOptions function throws an error.

emptyText string

Sets the empty text when no options are present.

loadingText string

Sets the loading text when the options are loading.

loadingMoreText string

Sets the loading text when more options are loading (via pagination).

renderClearButton any

renderError any

renderEmpty any

renderLoading any

renderLoadingMore any

renderOption any

clearButtonProps

{
  unstable_system?: any;
  defaultChecked?: boolean;
  defaultValue?: string | number | string[];
  suppressContentEditableWarning?: boolean;
  suppressHydrationWarning?: boolean;
  accessKey?: string;
  ... 807 more ...;
  ignoreGrayOverride?: boolean;
}

inputProps

{
  unstable_system?: any;
  top?: string | number | {
    [key: string]: string
  }; right?: string | number | {
    [key: string]: string
  }; bottom?: string | number | {
    [key: string]: string
  }; left?: string | number | {
    [key: string]: string
  }; ... 809 more ...;
  onFocus?: (event: FocusEvent<...>) => void;
}

itemProps

{
  unstable_system?: any;
  defaultChecked?: boolean;
  defaultValue?: string | number | string[];
  suppressContentEditableWarning?: boolean;
  suppressHydrationWarning?: boolean;
  accessKey?: string;
  ... 816 more ...;
  isTabbable?: boolean;
}

popoverProps

{
  unstable_system?: any;
  defaultChecked?: boolean;
  defaultValue?: string | number | string[];
  suppressContentEditableWarning?: boolean;
  suppressHydrationWarning?: boolean;
  accessKey?: string;
  ... 817 more ...;
  isTabbable?: boolean;
}

dropdownMenuInitialState

{
  baseId?: string;
  unstable_virtual?: boolean;
  currentId?: string;
  orientation?: Orientation;
  wrap?: boolean | "horizontal" | "vertical";
  rtl?: boolean;
  loop?: boolean | "horizontal" | "vertical";
  ... 11 more ...;
  unstable_preventOverflow?: boolean;
}
Inherits Box props

use

string
  | (ComponentClass<any, any> & { useProps: any; })
  | (FunctionComponent<any> & { useProps: any; })

className string

children

string
  | number
  | boolean
  | {}
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<...>)>
  | ReactNodeArray
  | ReactPortal
  | ((props: BoxProps) => ReactNode)

alignX "right" | "left" | "center"

alignY "top" | "bottom" | "center"

colorMode string

overrides

{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 95 more ...;
  Template?: TemplateThemeConfig;
}

elementRef ((instance: any) => void) | RefObject<any>

themeKey string

Inherits FieldWrapper props

description

string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Sets the description text of the field wrapper.

hint

string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Sets the bottom hint text of the field wrapper.

isOptional boolean

Sets the optional flag (and displays optional text) on the field wrapper.

isRequired boolean

Sets the required flag (and a required astrix) on the field wrapper.

labelType "label" | "legend"

Sets the label type on the field wrapper.

tooltip

string
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Sets the tooltip of the field wrapper. Can be either a string, or a React component.

tooltipTriggerComponent

ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<any, any, any>)>

Sets the tooltip trigger component.

validationText string

Sets the bottom validation text of the field wrapper.

Theming#

Autosuggest.styles.base
Autosuggest.Input.styles.base
Autosuggest.Popover.styles.base
Autosuggest.Item.styles.base
Autosuggest.ItemText.styles.base
Autosuggest.ClearButtonWrapper.styles.base
Autosuggest.ClearButton.styles.base
Autosuggest.StaticItem.styles.base
Copyright © 2021 Jake Moxey