Lookup
A Lookup is a predictive text input that presents a dropdown menu with suggestions based on the current input value.
Guidelines
When to use lookups
Use the Lookup component to let users search through a dataset to choose a predefined value for a form field. This can be useful when there are many options the user can choose from, so they need to filter the items via a text query.
Avoid using Lookup to enable users to search for and navigate to content. Instead, use SearchInput or TypeaheadSearch.
Specifications
Lookup includes the following elements:
- Input
A TextInput where the user types to look for the suggested results. This can optionally include a start icon, clear button, and placeholder text. - Dropdown menu
Suggested results are displayed via the Menu component.
Component limitations
Since the Lookup component uses a TextInput, its base min-width
is set to size-1600
token (equivalent to 256px
in the default Codex theme), but it can be customized to a smaller width if needed. There is no maximum width set. If the text entered in the input exceeds the available space, it will overflow horizontally.
Refer to the Lookup component in Codex Figma.
Types
An input field featuring an optional placeholder will enable users to initiate their search for suggested results. These suggestions will be displayed within a dropdown menu, and if the menu cannot fully accommodate the results, a scrollbar with the choice of infinite scroll can be included.
Clearable, with start icon
An optional start icon and clear button could appear within the input field.
With custom menu item display
Custom content and formats can be applied to change the appearance of menu items according to your needs.
With initial suggestions
When the input field is focused, an initial list of suggestions may appear within the menu. When typing within the input field, these suggestions disappear, and the menu showcases a list of items matching the typed value. It is advisable to include a minimum of 2 suggested items and ideally limit the maximum to 4 or 5 items.
No results
If there are no results for the text typed by the user, a non-interactive "no results" message will be displayed within the menu.
Lookup within a form field
A Lookup can be wrapped within a Field to include features like label, description, help text, or validation messages.
Interaction states
Interaction can take place within both the input and the displayed menu:
- Default
- Hover
- Focus
- Active
- Filled
- Filled active (with a menu item selected)
- Error
- Error hover
- Disabled
Best practices
Consider the following recommendations when using Lookups.
- Wrap the Lookup within the Field component to incorporate features such as labels, descriptions, help text, or validation messages.
- Use a standalone Lookup on a page.
Keyboard navigation
Key | Function |
---|---|
Down arrow | When the focus is placed on the Lookup, it opens the menu. When the menu is open, pressing it navigates through menu options. If pressed at the last visible option, it scrolls to the next "hidden" menu item. |
Up arrow | When the focus is placed on the Lookup, it opens the menu. When the menu is open, it navigates through menu options. |
Esc | When the menu is open, it closes the menu. |
Enter | It opens the menu when the focus is placed on the Lookup. If the menu is open, it closes the menu. If the focus is placed in any of the options within the menu, the focused option is selected. |
Demos
Configurable
Name | Value |
---|---|
Props | |
status | |
disabled | |
View | |
Reading direction |
Default
The Lookup component will emit input
events on input, which the parent component should react to by computing or fetching menu items, then providing those items to the Lookup component for display by updating the menu-items
prop.
Items are displayed via the MenuItem component—see the MenuItem docs for more options. In this example, a menuConfig
object is passed to the Lookup to bold the label text.
Note that in this example, menu items are Wikidata items with a human-readable label and a Wikidata entity ID value.
WARNING
The parent component must update the menu-items
prop after each input
event, otherwise the Lookup component will stay in the pending state indefinitely. If there are no results for the given input, set the menu-items
prop to an empty array ([]
).
Selected value:
Name | Value |
---|---|
View | |
Reading direction |
With custom menu item display
The menu-item
slot can be used to set up custom menu item content and formatting.
With "no results" content
A non-interactive "no results" message can be displayed via the no-results
slot. If populated, this slot will automatically display when there are zero menu items.
With initial suggestions
You can show an initial list of options as "suggestions" by passing in an array of menu items initially. The parent component must handle resetting the menu items to this list of suggestions when the input is cleared.
Selected value:
Name | Value |
---|---|
View | |
Reading direction |
With initial selection and input
To set an initial selection, do the following:
- Set the
selected
prop to the value of the initially selected item. - Use the optional
v-model:input-value
prop to set the input value to the label of the selected item (or the value, if there is no label). - Optional: if you want the selected item to appear in the menu when it is opened, you must provide the selected item in the list of
menuItems
. Otherwise, you can initializemenuItems
to an empty array or a list of initial suggestions.
You can also use v-model:input-value
to set an initial input value without an initial selection.
Selected value: Q81
With fetched results and infinite scroll
Often, Lookup is used to fetch results from an API endpoint. Parent components should react to the input
event emitted by Lookup to search for results, then pass back to the Lookup either an array of results to display as menu items or an empty array if there are no results. Between those two events, a pending state animation will display in the input.
Scrolling is enabled by setting the visibleItemLimit
property of the menuConfig
prop.
With scrolling enabled, when the user nears the end of the list of results, a load-more
event is emitted. The parent component can react to this by fetching more results and appending them to the list of menu items provided to the Lookup. These new items will then be displayed within the menu.
Clearable, with start icon
Props of the TextInput component can be bound to Lookup and will be passed down to the TextInput component inside of it, so you can take advantage of features like the "clear" button and icons.
With placeholder
Attributes (except for class
) will fall through to the input element, so you can set things like placeholder
on the Lookup component and they'll be applied to the input.
Form field
A Lookup can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.
Vue usage
Typical use of this component will involve listening for input
events, fetching or otherwise computing menu items, then passing those menu items back to the Lookup for display.
TextInput props apply
This component contains a TextInput component. You can bind TextInput props to this component and they will be passed to the TextInput within.
Attributes passed to input
This component will pass any HTML attributes applied to it, except for CSS class, to the <input>
element within the component.
Props
Prop name | Description | Type | Default |
---|---|---|---|
selected (required) | Value of the current selection. Must be bound with v-model:selected .The property should be initialized to null rather than using a falsy value. | string|number|null | |
menuItems (required) | Menu items. | MenuItemData[] | |
inputValue | Current value of the input. This prop is optional and should only be used if you need to keep track of the input value for some reason (e.g. to set an initial value). Optionally provided by v-model:input-value binding in the parent component. | string|number | null |
initialInputValue | Initial value of the text input. Non-reactive.@deprecated Use inputValue instead. | string|number | '' |
disabled | Whether the entire component is disabled. | boolean | false |
menuConfig | Configuration for various menu features. All properties default to false. See the MenuConfig type. | MenuConfig | {} |
status | status property of the TextInput component | ValidationStatusType | 'default' |
Events
Event name | Properties | Description |
---|---|---|
change | event Event | When an input value change is committed by the user (e.g. on blur) |
load-more | When the user scrolls towards the bottom of the menu. If it is possible to add or load more menu items, then now would be a good moment so that the user can experience infinite scrolling. | |
update:selected | selected string|number|null - The new selected value | When the selected value changes. |
update:input-value | inputValue string|number - The new input value | When the input value changes. Only emitted if the inputValue prop is provided. |
input | value string|number - The new value | When the text input value changes. |
focus | event FocusEvent | When the input comes into focus |
blur | event FocusEvent | When the input loses focus |
Slots
Name | Description | Bindings |
---|---|---|
menu-item | Display of an individual item in the menu | menu-item MenuItemData - The current menu item |
no-results | Message to show if there are no results to display. |
CSS-only version
Markup structure
There is no true CSS-only version of the Lookup component. However, a CSS-only TextInput component can be used instead, since it has visual parity with the Lookup component with its menu collapsed. For example, you could display a CSS-only TextInput on page load while a Vue app loads, then replace it with the Vue Lookup component once the Vue app has mounted.
The example below is a simple text input with a placeholder, but icons and different states are supported—see the TextInput docs for more information.