#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

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

#Automatic selection

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

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

#Loading indicator

You can render a loading indicator with the isLoading prop.

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

#Custom empty text

You can render custom empty text with the emptyText prop.

#Custom empty component

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

#Option icons

#Disabled

#Disabled item

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

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

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

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

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.

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

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;
  ... 798 more ...;
  spinnerProps?: SpinnerProps;
}

inputProps

{
  children?: string | number | boolean | {
     | (string & {
      ) | (number & {
        ) | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<...>)> | ... 45 more ... | (ReactPortal & ((props: BoxProps) => ReactNode));
        ......

itemProps

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

popoverProps

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

dropdownMenuInitialState

{
  baseId?: string;
  unstable_virtual?: boolean;
  orientation?: "horizontal" | "vertical";
  currentId?: string;
  rtl?: boolean;
  loop?: boolean | "horizontal" | "vertical";
  wrap?: boolean | "horizontal" | "vertical";
  ... 10 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 "left" | "right" | "center"

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

altitude string

variant string

colorMode string

overrides

{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 94 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;
  ... 804 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.

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.

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

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;
  ... 798 more ...;
  spinnerProps?: SpinnerProps;
}

inputProps

{
  children?: string | number | boolean | {
     | (string & {
      ) | (number & {
        ) | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)>) | (new (props: any) => Component<...>)> | ... 45 more ... | (ReactPortal & ((props: BoxProps) => ReactNode));
        ......

itemProps

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

popoverProps

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

dropdownMenuInitialState

{
  baseId?: string;
  unstable_virtual?: boolean;
  orientation?: "horizontal" | "vertical";
  currentId?: string;
  rtl?: boolean;
  loop?: boolean | "horizontal" | "vertical";
  wrap?: boolean | "horizontal" | "vertical";
  ... 10 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 "left" | "right" | "center"

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

altitude string

variant string

colorMode string

overrides

{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 94 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.

label

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 label 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 © 2020 Jake Moxey