Lookup

Lookup in Storybook

The lookup component allows users to select a value from among the available values using keywords. It can be a primary source for discovering or filtering content.

If used as a search bar, the placement of the search bar determines the range of the search and its results.

• Search bars placed on a header will search across the entire application for results.
• Search bars placed within an element will only search within the element for results.

Anatomy

The lookup component appears with a label, an input field, and an icon.

Lookup consists of:

1. Label: establishes context for the user's search.
2. Input field: allows users to input keywords, text, and specific words.
3. (If used as search) Search icon: triggers the search when clicked.
4. Clear icon: removes all content from the input field.

Best practices

• Use placeholder text to guide users about appropriate terms for the context.
• Include autosuggestion wherever possible.
• Clearly state the categories of the available values.
• Have a clear empty-state message that directs users to the next step and offers suggestions for moving forward. (See UX writing considerations below).
• Use lookups and searches sparingly across your application. Not every element requires a lookup or search.
• Highlight the terms that the user entered in the results.
• Add descriptions to results to help users navigate and pick the accurate option.
• Display the number of results returned.
• Keep the original text after users execute the query.
• Use a processing icon if retrieving values takes more than 5 seconds.
• Users understand the purpose of a lookup field; therefore, only use a content-specific label (instead of a generic term like 'search').x

Interactions

Lookup has an enabled, disabled, active, and focus state.

• Enabled: Communicates to the user that the element is enabled for interaction (default).
• Disabled: Communicates to the user that the element is not interactive.
• Focus: Provides feedback indicating that the element is highlighted by using a keyboard or mouse.
• Active: Provides feedback indicating that the user is clicking or tapping the element.

When the user clicks into the lookup field, the cursor 'blinks' until the user starts to type.

Users should be able to initiate the operation via both the icon and the return key.

Navigation

• When the user selects the icon or presses the return key, the results are shown below the search field.
• How the user navigates the results is on a per application basis.

Error conditions

If there are no results based on the criteria, a message appears and encourages next steps whenever possible.

UX writing considerations

Empty states

• When writing for empty states (for example, searches that return no results), avoid telling users what there isn't. Instead, use the opportunity to communicate what there is.
• Do NOT use terms like system, queries, or values. For example, "No results were found for the values entered," or "The query produced no results."
• Empty states for search results should direct users to the next step and keep them moving through the product flow.
• Explain the situation. Let users know that you haven't found what they were looking for. Your tone should be empathetic.
• Suggest alternative ways to progress forward that are relevant to your type of content, for example:
  • There are usually multiple ways to search for the same thing. This includes searching by category, searching for a more general or specific term, trying to use synonyms, and checking spelling.
  • Are there things that are similar to what the user searched for? You can suggest items or links that are as close as possible. For example:
    • Items by the same manufacturer (for example, other Ford vehicles).
    • Items with similar specifications from different manufacturers (for example, 2010 vehicles).
    • Items that are of a similar type, style, or feature (for example, midsize sedans).
  • Can your search engine find similar terms? If so, consider offering these results to users to save them the hassle of performing another search.
• It's critical to understand what users are trying to accomplish with their search. Offer users something that gets them closer to their goal.
• Aim for language that is friendly and conversational, for example, "We couldn't find any results. Did you mean [link to similar term]? Try searching for something else or broadening your search."

Placeholder text

• Use placeholder text to help scaffold the experience. For instance, you can reduce the range of choices by defining categories within the search field. This enables users to focus on the possibilities and guides them as they perform their search.
• Alternatively, consider asking users a direct question (preferably in the second person "you") in fields that are particularly important. This will motivate users to find answers and dive into the site.

Accessibility

The Jutro lookup component is used to look up a specific value from a pre-populated list of values.

• Screen reader interaction: The input field & label are associated via the aria-labelledby WAI-ARIA attribute. The field also includes the value of aria-autocomplete="list" to indicate that it contains a list popup with autocomplete function. As you type, the input field pre-populates a dropdown list of values that mostly closely matches what is entered in the field. The option that matches the information typed is automatically focused upon and is voiced by a screen reader.
• Keyboard interaction: Pressing TAB moves keyboard focus to the input field. Pressing SPACEBAR or the down arrow key open the popup menu with a list of values. The list is refined by typing the first few characters of the name you require.
• Color: The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.0 AA requirements.
• Zoom: All content is visible and functional up to & including a zoom factor of 200%.

Using the lookup field

LookupField is a component that allows users to search for data. It displays a list of data objects with icons and categories.

When a user selects the Lookup component, a drop-down displays recent search results. The user can type in the field to update the results to include only elements that match the entered text and can select a specific result from the list.

Option types

The optionTypes prop specifies the list of categories that the options can belong too, and some identifying characteristics for these options. For example:

{
    type: 'contact',
    icon: 'gw-perm-contact-calendar',
    className: styles.lookupOptionContact,
    displayName: {
        id: 'myOptionTypes.Contact',
        defaultMessage: 'Contact'
    },
},

Each data item can reference a type. If it references an predefined type, the value in the drop-down displays the icon and displayName, and uses the className specified for the type.

If the data item references an unknown type, the drop-down displays the default unknown type, including the icon, displayName, and className.

Loading values from a static list

You can pass values directly into the availableValues property, for example:

const lookupAvailableValues = [
  {
    id: '1',
    type: 'account',
    displayName: 'Marcello Carcia - 234567876551',
  },
  {
    id: '2',
    type: 'policy',
    displayName: 'Marine - 234567874321',
  },
  {
    id: '3',
    type: 'contact',
    displayName: 'Markus Latchford - 234567879698',
  },
];

Loading values asynchronously

You can load values from an external source, for example an API. To do that, create an asynchronous function and pass it to the onLoadValues prop.

function contactListLookup() {
  async function getContactsFromTheApi(textInput) {
    // implemented functionality
    return arrayOfResultsFilteredByTextInput;
  }

  const resolvers = useMemo(() => ({
    resolveCallbackMap: {
      getContactsFromTheApi: getContactsFromTheApi,
    },
  }));
}

Here's the presentation metadata for this example:

{
  "$schema": "../metadata.schema.json",
  "jutro": "10.3.0",
  "search.example": {
    "id": "lookup",
    "type": "field",
    "component": "Lookup",
    "componentProps": {
      "onLoadValues": "getContactsFromTheApi"
    }
  }
}