Name	Description	Default
propertyName*	This is a short description summary	defaultValue
propertyName*	This is a short description summary	defaultValue
propertyName*	This is a short description summary	defaultValue

Autocomplete

An autocomplete is a normal text input enhanced by a panel of suggested options.

usage: import { Autocomplete, Item, Section } from "@sharegate/orbit-ui";
wai-aria: https://www.w3.org/WAI/ARIA/apg/patterns/combobox
sources: Github

Usage

Default

A default autocomplete

Editable example

<Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete><Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete>

Sections

An autocomplete items can be group by sections.

Editable example

<Autocomplete placeholder="Planets" aria-label="Planets">
    <Section title="Visited">
        <Item key="earth">Earth</Item>
        <Item key="mars">Mars</Item>
        <Item key="saturn">Saturn</Item>
    </Section>
    <Section title="Not Visited">
        <Item key="jupiter">Jupiter</Item>
        <Item key="mercury">Mercury</Item>
        <Item key="neptune">Neptune</Item>
        <Item key="uranus">Uranus</Item>
    </Section>
</Autocomplete><Autocomplete placeholder="Planets" aria-label="Planets">
    <Section title="Visited">
        <Item key="earth">Earth</Item>
        <Item key="mars">Mars</Item>
        <Item key="saturn">Saturn</Item>
    </Section>
    <Section title="Not Visited">
        <Item key="jupiter">Jupiter</Item>
        <Item key="mercury">Mercury</Item>
        <Item key="neptune">Neptune</Item>
        <Item key="uranus">Uranus</Item>
    </Section>
</Autocomplete>

Item icon

An autocomplete item can have icons.

Editable example

<Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <PlaceholderMajorIcon />
        <Text>Earth</Text>
    </Item>
    <Item key="jupiter">
        <PlaceholderMajorIcon />
        <Text>Jupiter</Text>
    </Item>
    <Item key="mars">
        <PlaceholderMajorIcon />
        <Text>Mars</Text>
    </Item>
</Autocomplete><Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <PlaceholderMajorIcon />
        <Text>Earth</Text>
    </Item>
    <Item key="jupiter">
        <PlaceholderMajorIcon />
        <Text>Jupiter</Text>
    </Item>
    <Item key="mars">
        <PlaceholderMajorIcon />
        <Text>Mars</Text>
    </Item>
</Autocomplete>

Item end icon

An autocomplete item can have non standard end icons can be provided to handle special cases like displaying a list of icons. However, think twice before adding end icons, start icons should be your go to.

Editable example

<Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <Text>Earth</Text>
        <IconList slot="end-icon">
            <UfoMajorIcon />
            <TelescopeMajorIcon />
            <RocketMajorIcon />
        </IconList>
    </Item>
    <Item key="jupiter">
        <Text>Jupiter</Text>
        <PlaceholderMajorIcon slot="end-icon" />
    </Item>
    <Item key="mars">
        <Text>Mars</Text>
        <IconList slot="end-icon">
            <UfoMajorIcon />
            <TelescopeMajorIcon />
            <RocketMajorIcon />
        </IconList>
    </Item>
</Autocomplete><Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <Text>Earth</Text>
        <IconList slot="end-icon">
            <UfoMajorIcon />
            <TelescopeMajorIcon />
            <RocketMajorIcon />
        </IconList>
    </Item>
    <Item key="jupiter">
        <Text>Jupiter</Text>
        <PlaceholderMajorIcon slot="end-icon" />
    </Item>
    <Item key="mars">
        <Text>Mars</Text>
        <IconList slot="end-icon">
            <UfoMajorIcon />
            <TelescopeMajorIcon />
            <RocketMajorIcon />
        </IconList>
    </Item>
</Autocomplete>

Item description

An autocomplete item can have a description.

Editable example

<Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <Text>Earth</Text>
        <Text slot="description">Home sweet home!</Text>
    </Item>
    <Item key="jupiter">
        <Text>Jupiter</Text>
        <Text slot="description">The fourth-brightest object in the sky</Text>
    </Item>
    <Item key="mars">
        <Text>Mars</Text>
        <Text slot="description">See you in 2026</Text>
    </Item>
</Autocomplete><Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <Text>Earth</Text>
        <Text slot="description">Home sweet home!</Text>
    </Item>
    <Item key="jupiter">
        <Text>Jupiter</Text>
        <Text slot="description">The fourth-brightest object in the sky</Text>
    </Item>
    <Item key="mars">
        <Text>Mars</Text>
        <Text slot="description">See you in 2026</Text>
    </Item>
</Autocomplete>

A description can be paired with an icon.

Editable example

<Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <PlaceholderMajorIcon />
        <Text>Earth</Text>
        <Text slot="description">Home sweet home!</Text>
    </Item>
    <Item key="jupiter">
        <PlaceholderMajorIcon />
        <Text>Jupiter</Text>
        <Text slot="description">The fourth-brightest object in the sky</Text>
    </Item>
    <Item key="mars">
        <PlaceholderMajorIcon />
        <Text>Mars</Text>
        <Text slot="description">See you in 2026</Text>
    </Item>
</Autocomplete><Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <PlaceholderMajorIcon />
        <Text>Earth</Text>
        <Text slot="description">Home sweet home!</Text>
    </Item>
    <Item key="jupiter">
        <PlaceholderMajorIcon />
        <Text>Jupiter</Text>
        <Text slot="description">The fourth-brightest object in the sky</Text>
    </Item>
    <Item key="mars">
        <PlaceholderMajorIcon />
        <Text>Mars</Text>
        <Text slot="description">See you in 2026</Text>
    </Item>
</Autocomplete>

A description can be paired with an avatar.

Editable example

<Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <Avatar name="Earth" />
        <Text>Earth</Text>
        <Text slot="description">Home sweet home!</Text>
    </Item>
    <Item key="jupiter">
        <Avatar name="Jupiter" />
        <Text>Jupiter</Text>
        <Text slot="description">The fourth-brightest object in the sky</Text>
    </Item>
    <Item key="mars">
        <Avatar name="Mars" />
        <Text>Mars</Text>
        <Text slot="description">See you in 2026</Text>
    </Item>
</Autocomplete><Autocomplete placeholder="Planets" aria-label="Planets">
    <Item key="earth">
        <Avatar name="Earth" />
        <Text>Earth</Text>
        <Text slot="description">Home sweet home!</Text>
    </Item>
    <Item key="jupiter">
        <Avatar name="Jupiter" />
        <Text>Jupiter</Text>
        <Text slot="description">The fourth-brightest object in the sky</Text>
    </Item>
    <Item key="mars">
        <Avatar name="Mars" />
        <Text>Mars</Text>
        <Text slot="description">See you in 2026</Text>
    </Item>
</Autocomplete>

Trigger icon

An autocomplete trigger can have an icon.

Editable example

<Autocomplete icon={<MagnifierMajorIcon />} placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete><Autocomplete icon={<MagnifierMajorIcon />} placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete>

Disabled

Editable example

<Autocomplete disabled placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete><Autocomplete disabled placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete>

Readonly

Editable example

<Autocomplete readOnly placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete><Autocomplete readOnly placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete>

Fluid

An autocomplete can take the width of it's container.

Editable example

<Autocomplete fluid placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete><Autocomplete fluid placeholder="Planets" aria-label="Planets">
    <Item key="earth">Earth</Item>
    <Item key="jupiter">Jupiter</Item>
    <Item key="mars">Mars</Item>
    <Item key="mercury">Mercury</Item>
    <Item key="neptune">Neptune</Item>
    <Item key="saturn">Saturn</Item>
    <Item key="uranus">Uranus</Item>
</Autocomplete>

Validation

An autocomplete can display a validation state to communicate to the user whether the current value is valid or invalid. Implement your own validation logic in your app and pass either "valid" or "invalid" to the input via the validationState prop.

The example below illustrates how one would validate that a specific value have been selected.

Editable example

() => {
    const [isValid, setIsValid] = useState(true);

    const handleSelectionChange = useCallback(
        (event, selection) => {
            setIsValid(!isNil(selection) && selection.key === "earth");
            console.log(selection);
        },
        [setIsValid]
    );

    return (
        <Autocomplete
            validationState={isValid ? "valid" : "invalid"}
            placeholder="Planets"
            onSelectionChange={handleSelectionChange}
            aria-label="Planets"
        >
            <Item key="earth">Earth</Item>
            <Item key="jupiter">Jupiter</Item>
            <Item key="mars">Mars</Item>
            <Item key="mercury">Mercury</Item>
            <Item key="neptune">Neptune</Item>
            <Item key="saturn">Saturn</Item>
            <Item key="uranus">Uranus</Item>
        </Autocomplete>
    );
};() => {
    const [isValid, setIsValid] = useState(true);

    const handleSelectionChange = useCallback(
        (event, selection) => {
            setIsValid(!isNil(selection) && selection.key === "earth");
            console.log(selection);
        },
        [setIsValid]
    );

    return (
        <Autocomplete
            validationState={isValid ? "valid" : "invalid"}
            placeholder="Planets"
            onSelectionChange={handleSelectionChange}
            aria-label="Planets"
        >
            <Item key="earth">Earth</Item>
            <Item key="jupiter">Jupiter</Item>
            <Item key="mars">Mars</Item>
            <Item key="mercury">Mercury</Item>
            <Item key="neptune">Neptune</Item>
            <Item key="saturn">Saturn</Item>
            <Item key="uranus">Uranus</Item>
        </Autocomplete>
    );
};

Form

An autocomplete can be part of a form. To submit the value of a select, make sure you specify the name property.

Editable example

<form>
    <Autocomplete name="planet" placeholder="Planets" aria-label="Planets">
        <Item key="earth">Earth</Item>
        <Item key="jupiter">Jupiter</Item>
        <Item key="mars">Mars</Item>
        <Item key="mercury">Mercury</Item>
        <Item key="neptune">Neptune</Item>
        <Item key="saturn">Saturn</Item>
        <Item key="uranus">Uranus</Item>
    </Autocomplete>
</form><form>
    <Autocomplete name="planet" placeholder="Planets" aria-label="Planets">
        <Item key="earth">Earth</Item>
        <Item key="jupiter">Jupiter</Item>
        <Item key="mars">Mars</Item>
        <Item key="mercury">Mercury</Item>
        <Item key="neptune">Neptune</Item>
        <Item key="saturn">Saturn</Item>
        <Item key="uranus">Uranus</Item>
    </Autocomplete>
</form>

Dynamic items

An autocomplete items can be rendered dynamically.

Editable example

<Autocomplete placeholder="Planets" aria-label="Planets">
    {["Earth", "Jupiter", "Mars", "Mercury", "Neptune", "Saturn", "Uranus"].map(x => (
        <Item key={x.toLowerCase()}>{x}</Item>
    ))}
</Autocomplete><Autocomplete placeholder="Planets" aria-label="Planets">
    {["Earth", "Jupiter", "Mars", "Mercury", "Neptune", "Saturn", "Uranus"].map(x => (
        <Item key={x.toLowerCase()}>{x}</Item>
    ))}
</Autocomplete>

Remote items

An autocomplete items can be fetch from a remote source.

We provide an utility hook called useAsyncSearch which accept an async function responsible of fetching the data. You could roll your own utility hook as long as it returns a loading indicator and provide a function to handle search requests.

In most cases, you should pass the signal arg to your fetch request.

Editable example

() => {
    const fetcher = useAsyncSearch(async (query, signal) => {
        const response = await fetch(
            `https://wft-geo-db.p.rapidapi.com/v1/geo/countries?namePrefix=${query}`,
            {
                method: "GET",
                headers: {
                    "x-rapidapi-key": ApiKey,
                    "x-rapidapi-host": "wft-geo-db.p.rapidapi.com",
                    useQueryString: true
                },
                signal
            }
        );

        const json = await response.json();

        return json.data.map(x => ({
            key: x.code,
            value: x.name
        }));
    });

    return (
        <Autocomplete
            loading={fetcher.isLoading}
            onSearch={fetcher.search}
            placeholder="Select a country"
            aria-label="Countries"
        >
            {fetcher.items.map(x => (
                <Item key={x.key}>{x.value}</Item>
            ))}
        </Autocomplete>
    );
};() => {
    const fetcher = useAsyncSearch(async (query, signal) => {
        const response = await fetch(
            `https://wft-geo-db.p.rapidapi.com/v1/geo/countries?namePrefix=${query}`,
            {
                method: "GET",
                headers: {
                    "x-rapidapi-key": ApiKey,
                    "x-rapidapi-host": "wft-geo-db.p.rapidapi.com",
                    useQueryString: true
                },
                signal
            }
        );

        const json = await response.json();

        return json.data.map(x => ({
            key: x.code,
            value: x.name
        }));
    });

    return (
        <Autocomplete
            loading={fetcher.isLoading}
            onSearch={fetcher.search}
            placeholder="Select a country"
            aria-label="Countries"
        >
            {fetcher.items.map(x => (
                <Item key={x.key}>{x.value}</Item>
            ))}
        </Autocomplete>
    );
};

Custom search

An autocomplete search strategy can be customized by providing an onSearch handler.

Editable example

const Planets = [
    { key: "earth", value: "Earth", canShow: true },
    { key: "jupiter", value: "Jupiter", canShow: true },
    { key: "mars", value: "Mars", canShow: true },
    { key: "mercury", value: "Mercury", canShow: false },
    { key: "neptune", value: "Neptune", canShow: false },
    { key: "saturn", value: "Saturn", canShow: false },
    { key: "uranus", value: "Uranus", canShow: false }
];

() => {
    const [selectedPlanets, setSelectedPlanets] = useState(Planets);

    const handleSearch = useCallback(
        (event, query) => {
            setSelectedPlanets(
                Planets.filter(
                    x => x.value.toLowerCase().startsWith(query.toLowerCase()) && x.canShow
                )
            );
        },
        [setSelectedPlanets]
    );

    return (
        <Autocomplete onSearch={handleSearch} placeholder="Planets" aria-label="Planets">
            {selectedPlanets.map(x => (
                <Item key={x.key}>{x.value}</Item>
            ))}
        </Autocomplete>
    );
};const Planets = [
    { key: "earth", value: "Earth", canShow: true },
    { key: "jupiter", value: "Jupiter", canShow: true },
    { key: "mars", value: "Mars", canShow: true },
    { key: "mercury", value: "Mercury", canShow: false },
    { key: "neptune", value: "Neptune", canShow: false },
    { key: "saturn", value: "Saturn", canShow: false },
    { key: "uranus", value: "Uranus", canShow: false }
];

() => {
    const [selectedPlanets, setSelectedPlanets] = useState(Planets);

    const handleSearch = useCallback(
        (event, query) => {
            setSelectedPlanets(
                Planets.filter(
                    x => x.value.toLowerCase().startsWith(query.toLowerCase()) && x.canShow
                )
            );
        },
        [setSelectedPlanets]
    );

    return (
        <Autocomplete onSearch={handleSearch} placeholder="Planets" aria-label="Planets">
            {selectedPlanets.map(x => (
                <Item key={x.key}>{x.value}</Item>
            ))}
        </Autocomplete>
    );
};

Controlled

The selectedKey and open state can be handled in controlled mode.

Editable example

() => {
    const [isOpen, setIsOpen] = useState(false);
    const [value, setValue] = useState("Mars");

    const handleOpenChange = useCallback(
        (event, newValue) => {
            setIsOpen(newValue);
            console.log(newValue);
        },
        [setIsOpen]
    );

    const handleSelectionChange = useCallback(
        (event, selection) => {
            setValue(!isNil(selection) ? selection.value : null);
            console.log(selection);
        },
        [setValue]
    );

    return (
        <Autocomplete
            open={isOpen}
            value={value}
            placeholder="Planets"
            onOpenChange={handleOpenChange}
            onSelectionChange={handleSelectionChange}
            aria-label="Planets"
        >
            <Item key="earth">Earth</Item>
            <Item key="jupiter">Jupiter</Item>
            <Item key="mars">Mars</Item>
            <Item key="mercury">Mercury</Item>
            <Item key="neptune">Neptune</Item>
            <Item key="saturn">Saturn</Item>
            <Item key="uranus">Uranus</Item>
        </Autocomplete>
    );
};() => {
    const [isOpen, setIsOpen] = useState(false);
    const [value, setValue] = useState("Mars");

    const handleOpenChange = useCallback(
        (event, newValue) => {
            setIsOpen(newValue);
            console.log(newValue);
        },
        [setIsOpen]
    );

    const handleSelectionChange = useCallback(
        (event, selection) => {
            setValue(!isNil(selection) ? selection.value : null);
            console.log(selection);
        },
        [setValue]
    );

    return (
        <Autocomplete
            open={isOpen}
            value={value}
            placeholder="Planets"
            onOpenChange={handleOpenChange}
            onSelectionChange={handleSelectionChange}
            aria-label="Planets"
        >
            <Item key="earth">Earth</Item>
            <Item key="jupiter">Jupiter</Item>
            <Item key="mars">Mars</Item>
            <Item key="mercury">Mercury</Item>
            <Item key="neptune">Neptune</Item>
            <Item key="saturn">Saturn</Item>
            <Item key="uranus">Uranus</Item>
        </Autocomplete>
    );
};

API

Autocomplete

usage: import { Autocomplete } from "@sharegate/orbit-ui";
extends: Input
StyleProps

Name Description Default

align

The horizontal alignment of the popup relative to the trigger.

"end""start"

allowFlip

Whether or not the popup can flip when it will overflow it's boundary area.

falsetrue

allowPreventOverflow

Whether or not the popup position can change to prevent it from being cut off so that it stays visible within its boundary area.

falsetrue

autoFocus

Whether or not the input should autoFocus on render.

numberfalsetrue

children*

React children.

clearOnSelect

Whether or not the query should be cleared when a result is selected.

falsetrue

defaultOpen

The initial value of open when in auto controlled mode.

falsetrue

defaultValue

The default value of value when uncontrolled.

string

direction

The direction the open will open relative to the trigger.

"bottom""top"

fluid

Whether or not the autocomplete take up the width of its container.

false | true | ResponsiveValue<boolean>

icon

A trigger icon.

ReactElement<any, string | JSXElementConstructor<any>>

Whether or not the autocomplete should display a loading state.

falsetrue

minCharacters

Minimum characters to query for results.

number

noResultsMessage

Message to display when there are no results matching the query.

string

onOpenChange

Called when the open state change.

(event: SyntheticEvent<Element, Event>, isOpen: boolean) => void

`event`	React's original event.
`isOpen`	Indicate if the popup is visible.

onSearch

Called when the input query change and new search results are expected.

(event: SyntheticEvent<Element, Event>, query: string) => void

`event`	React's original event.
`query`	The search query.

onSelectionChange

Called when the autocomplete value change.

(event: SyntheticEvent<Element, Event>, selection: { key: string; value: string; }) => void

`event`	React's original event.
`selection`	The new selection.

open

Whether or not to show the popup.

falsetrue

overlayProps

Additional props to render on the menu of options.

Partial<Omit<OmitInternalProps<InnerOverlayProps, never>, "ref"> & RefAttributes<any>>

validationState

Whether or not the input should display as "valid" or "invalid".

"valid""invalid"

value

A controlled autocomplete value.

string

wrapperProps

Additional props to render on the wrapper element.

Partial<OmitInternalProps<InnerBoxProps, never> & RefAttributes<any>>

zIndex

The z-index of the menu.

number

Item

usage: import { Item } from "@sharegate/orbit-ui";
slots: "icon", "avatar", "text", "description", "end-icon"

Name	Description	Default
children	React children. string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| ReactFragment \| ReactPortal	-
key	A unique key to identify the item. string	-

Section

usage: import { Section } from "@sharegate/orbit-ui";

Name	Description	Default
children*	React children. string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| ReactFragment \| ReactPortal	-

No Preview

Autocomplete

Usage

Default

Sections

Item icon

Item end icon

Item description

Trigger icon

Disabled

Readonly

Fluid

Validation

Form

Dynamic items

Remote items

Custom search

Controlled

API

Autocomplete

Item

Section