Skip to main content
About Project Overview Contributing Getting Started Installation Usage Themes Customizing Frameworks React Vue Angular GitHub Light Dark System

Combobox

<terra-combobox> | TerraCombobox
Since 1.0 stable

Fuzzy-search for combobox with list autocomplete.

Cycle Statuses

Use to cycle status of combobox

<style>
  .hint {
    bottom: 0;
    color: var(--terra-color-neutral--600, var(--color-neutral--600));
    flex: 1 1 100%;
    font-size: 0.875rem;
    margin-block: 0;
    margin-bottom: 1rem;
    }
</style>
<terra-button id="cycleList">Cycle Statuses</terra-button>

<p class="hint">Use to cycle status of combobox</p>

<terra-combobox></terra-combobox>


<script type="module">
  // Select the terra-combobox element from the DOM
const element = document.querySelector('terra-combobox');

// Log the initial state of searchableList
console.log('Initial searchableList:', element.content);

// Define data for each type of SearchableList
const listItemData = [
    { name: 'Item1', title: 'Title1', value: 'Value1' },
    { name: 'Item2', title: 'Title2', value: 'Value2' },
     { name: 'Item3', title: 'Title3', value: 'Value3' }
];

// Assuming structure for GroupedListItem, here's a sample
const groupedListItemData = [
    {
        name: 'Group1',
        items: [
            { name: 'Item1', title: 'Title1', value: 'Value1' },
            { name: 'Item2', title: 'Title2', value: 'Value2' },
             { name: 'Item3', title: 'Title3', value: 'Value3' }
        ]
    },
    {
        name: 'Group2',
        items: [
            { name: 'Item4', title: 'Title4', value: 'Value4' },
            { name: 'Item5', title: 'Title5', value: 'Value5' },
            { name: 'Item6', title: 'Title6', value: 'Value6' }
        ]
    }
];

// Add an event listener to handle the custom 'terra-combobox-change' event
element.addEventListener('terra-combobox-change', (e) => {
    console.log('Combobox changed:', e.detail);
});



// Function to cycle through different SearchableList types on button click
let currentTypeIndex = 0;
let currentStatusIndex = 0;
function cycleSearchableList() {
    const statuses = ['INITIAL', 'PENDING', 'COMPLETE', 'ERROR']
    const types = ['ListItem', 'GroupedListItem'];
    const data = [listItemData, groupedListItemData];

    // Update the searchableList property with the next type
    element.status = statuses[currentStatusIndex]

    const content = {
        type: types[currentTypeIndex],
        ...(statuses[currentStatusIndex] === 'ERROR' ? {data: 'An Error Occurred'} : {data: data[currentTypeIndex]})
    };

    element.content = content

    console.log("element.content", JSON.stringify(content))

    document.querySelector("#cycleList").innerHTML = "Cycle Statuses" + " | " + statuses[currentStatusIndex]


    // Log the change for visibility
    console.log('Updated content to:', element.content);

    console.log("element status: ", element.status)

    // Move to the next type or wrap around
    currentStatusIndex = (currentStatusIndex + 1) % statuses.length;

    if(currentStatusIndex === 2) {
      currentTypeIndex = (currentTypeIndex + 1) % types.length;
    }
}

// Create a button element dynamically
const button = document.querySelector('#cycleList');
button.addEventListener('click', cycleSearchableList);

</script>

Examples

Default Combobox

<terra-combobox status='COMPLETE' content='{"type":"GroupedListItem","data":[{"name":"Group1","items":[{"name":"Item1","title":"Title1","value":"Value1"},{"name":"Item2","title":"Title2","value":"Value2"},{"name":"Item3","title":"Title3","value":"Value3"}]},{"name":"Group2","items":[{"name":"Item4","title":"Title4","value":"Value4"},{"name":"Item5","title":"Title5","value":"Value5"},{"name":"Item6","title":"Title6","value":"Value6"}]}]}'></terra-combobox>

Configured Variable Combobox

<terra-combobox placeholder="Search for items: e.g., albedo" hide-label hide-help status='COMPLETE' content='{"type": "GroupedListItem", "data" : [{"name":"Amos group","items":[{"name":"Item 1","title":"Title 1","value":"Value 1"},{"name":"Item 2","title":"Title 2","value":"Value 2"}]},{"name":"Ben group","items":[{"name":"Item 3","title":"Title 3","value":"Value 3"},{"name":"Item 4","title":"Title 4","value":"Value 4"}]},{"name":"Jon group","items":[{"name":"Item 5","title":"Title 5","value":"Value 5"},{"name":"Item 6","title":"Title 6","value":"Value 6"}]},{"name":"Krupa group","items":[{"name":"Item 7","title":"Title 7","value":"Value 7"},{"name":"Item 8","title":"Title 8","value":"Value 8"}]}]}'></terra-combobox>

[component-metadata:terra-combobox]

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/combobox/combobox.js"></script>

To import this component from the CDN using a JavaScript import:

import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/combobox/combobox.js';

To import this component using a bundler:

import '@nasa-terra/components/dist/components/combobox/combobox.js';

To import this component as a React component:

import TerraCombobox from '@nasa-terra/components/dist/react/combobox';

Properties

Name Description Reflects Type Default
label Label the combobox with this. string 'Search for Items'
name name the combobox with this. string 'Item'
placeholder Set a placeholder for the combobox with this. Defaults to the label’s value. string -
hideHelp
hide-help
Hide the combobox’s help text. When hidden, not rendered at all. boolean false
hideLabel
hide-label
Hide the combobox’s label text. When hidden, still presents to screen readers. boolean false
status status of the content 'INITIAL' | 'PENDING' | 'COMPLETE' | 'ERROR' 'INITIAL'
content content or data of the combobox. This could be of type string | GroupedListItem[] | ListItem[] | undefined Content { type: SearchableListType.GroupedListItem, data: [], }
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Custom Properties

Name Description Default
--host-height The height of the host element.
--help-height The height of the search help element.
--label-height The height of the input’s label element.

Learn more about customizing CSS custom properties.

Parts

Name Description
base A search element, the component’s base.
combobox An input element used for searching.
button A button used for toggling the listbox’s visibility.
listbox A ul that holds the clickable options.

Learn more about customizing CSS parts.