Autosuggest

Ready

The Autosuggest component enhances the search experience by dynamically presenting relevant suggestions in a flyout panel as the user types into the search input. This flyout appears directly beneath the search field and updates in real-time, offering predictive results based on user input, recent searches, popular queries, and contextual relevance.

Storybook docs

Preview

Open in Storybook

Code

Install

npm install @fbin-web/neighborhood-core

Import

import { NbhdAutosuggest } from '@fbin-web/neighborhood-core';

Usage

<nbhd-autosuggest search-term="products"> </nbhd-autosuggest>

<script>
  const autosuggest = document.querySelector('nbhd-autosuggest');

  autosuggest.breadcrumbs = [
    { label: 'Search Term 1', href: '/' },
    { label: 'Search 2', href: '/search' },
    { label: 'Another', href: '/another' },
    { label: 'One', href: '/one' },
    { label: 'Two', href: '/two' },
    { label: 'Three', href: '/three' },
  ];

  autosuggest.suggestions = [
    {
      title: 'Category',
      items: [
        { label: 'Electronics', href: '/electronics', external: true },
        { label: 'Clothing', href: '/clothing' },
        { label: 'Home & Garden', href: '/home-garden' },
      ],
    },
    {
      title: 'Price',
      items: [
        { label: 'Under $50', href: '/under-50' },
        { label: '$50 - $100', href: '/50-100' },
        { label: 'Over $100', href: '/over-100' },
      ],
    },
    {
      title: 'Next',
      items: [
        { label: 'Electronics', href: '/electronics' },
        { label: 'Clothing', href: '/clothing' },
        { label: 'Home & Garden', href: '/home-garden' },
      ],
    },
    {
      title: 'Test',
      items: [
        { label: 'Under $50', href: '/under-50' },
        { label: '$50 - $100', href: '/50-100' },
        { label: 'Over $100', href: '/over-100' },
      ],
    },
  ];

  autosuggest.products = [
    {
      title: 'Product 1',
      identifier: '1234A',
      media: {
        src: 'https://placehold.co/300x300@2x.png?text=Product+Image',
        alt: 'Product 1',
        type: 'image',
      },
      href: 'product-1',
    },
    {
      title: 'Product 2',
      identifier: '1234B',
      media: {
        src: 'https://placehold.co/300x300@2x.png?text=Product+Image',
        alt: 'Product 2',
        type: 'image',
      },
      href: 'product-2',
    },
    {
      title: 'Product 3',
      identifier: '1234C',
      media: {
        src: 'https://placehold.co/300x300@2x.png?text=Product+Image',
        alt: 'Product 3',
        type: 'image',
      },
      href: 'product-3',
    },
  ];
</script>

Install

npm install @fbin-web/neighborhood-react

Import

import { NbhdAutosuggest } from '@fbin-web/neighborhood-react';

Usage

import { NbhdAutosuggest } from '@fbin-web/neighborhood-react';

const breadcrumbs = [
  { label: 'Search Term 1', href: '/' },
  { label: 'Search 2', href: '/search' },
  { label: 'Another', href: '/another' },
  { label: 'One', href: '/one' },
  { label: 'Two', href: '/two' },
  { label: 'Three', href: '/three' },
];

const suggestions = [
  {
    title: 'Category',
    items: [
      { label: 'Electronics', href: '/electronics', external: true },
      { label: 'Clothing', href: '/clothing' },
      { label: 'Home & Garden', href: '/home-garden' },
    ],
  },
  {
    title: 'Price',
    items: [
      { label: 'Under $50', href: '/under-50' },
      { label: '$50 - $100', href: '/50-100' },
      { label: 'Over $100', href: '/over-100' },
    ],
  },
  {
    title: 'Next',
    items: [
      { label: 'Electronics', href: '/electronics' },
      { label: 'Clothing', href: '/clothing' },
      { label: 'Home & Garden', href: '/home-garden' },
    ],
  },
  {
    title: 'Test',
    items: [
      { label: 'Under $50', href: '/under-50' },
      { label: '$50 - $100', href: '/50-100' },
      { label: 'Over $100', href: '/over-100' },
    ],
  },
];

const products = [
  {
    title: 'Product 1',
    identifier: '1234A',
    media: {
      src: 'https://placehold.co/300x300@2x.png?text=Product+Image',
      alt: 'Product 1',
      type: 'image',
    },
    href: 'product-1',
  },
  {
    title: 'Product 2',
    identifier: '1234B',
    media: {
      src: 'https://placehold.co/300x300@2x.png?text=Product+Image',
      alt: 'Product 2',
      type: 'image',
    },
    href: 'product-2',
  },
  {
    title: 'Product 3',
    identifier: '1234C',
    media: {
      src: 'https://placehold.co/300x300@2x.png?text=Product+Image',
      alt: 'Product 3',
      type: 'image',
    },
    href: 'product-3',
  },
];

const App = () => (
  <>
    <NbhdAutosuggest
      searchTerm="products"
      breadcrumbs={breadcrumbs}
      suggestions={suggestions}
      products={products}></NbhdAutosuggest>
  </>
);

Usage

Use the Autosuggest component to enhance search functionality by providing real-time suggestions.
Pass breadcrumb data via the breadcrumbs property to display navigation at the top of the panel.
Provide product data through the products property to show relevant product results.
Configure the surface style using the surface property to match the overall design theme.
Supply suggestion list data using the suggestions property for dynamic search suggestions.
Set the search term with the searchTerm property to display it in the heading and button.
Customize the heading text with the heading property.
Label the call-to-action button using the ctaLabel property.
Limit the number of suggestion lists and items with maxSuggestionLists and maxSuggestionItems respectively.
Control the number of breadcrumbs displayed using the maxBreadcrumbs property.

Properties

Property	Attribute	Type	Default	Description
`breadcrumbs`	—	`BreadcrumbContent[]`	—	Array of breadcrumb content to display at the top of the autosuggest panel.
`products`	—	`ProductCardContent[]`	—	Array of product content to display in the results section.
`surface`	`surface`	`noneprimarysecondaryinverseinverse-secondary`	`primary`	The surface style for the component.
`suggestions`	—	`ListContent[]`	—	Array of suggestion list content to display in the suggestions section.
`searchTerm`	`search-term`	`string`	—	The search term to display in the heading and button.
`heading`	`heading`	`string`	`Search Results for`	The heading text displayed before the search term. Rendered as a heading at `heading-level`.
`label`	`label`	`string`	`Search suggestions`	Accessible name of the suggestions popup (a dialog of links) while it is open, when linked to nbhd-search with `autosuggest`.
`ctaLabel`	`cta-label`	`string`	`See more results for`	The label for the call-to-action button.
`maxSuggestionLists`	`max-suggestion-lists`	`number`	`3`	Maximum number of suggestion lists to display.
`maxSuggestionItems`	`max-suggestion-items`	`number`	`5`	Maximum number of items to display per suggestion list.
`maxBreadcrumbs`	`max-breadcrumbs`	`number`	`4`	Maximum number of breadcrumb items to display.
`maxProducts`	`max-products`	`number`	`4`	Maximum number of products to display. Adjusts dynamically based on container width.
`headingLevel`	`heading-level`	`23456`	`3`	Heading level of the "Search Results for" heading and the suggestion list titles. Product titles are one level below.
`suggestionsAnnouncement`	`suggestions-announcement`	`string`	`{count} suggestions`	Announced to screen readers when results update. `{count}` is replaced with the number of suggestions shown.
`productsAnnouncement`	`products-announcement`	`string`	`{count} products`	Announced with the suggestions count when results update. `{count}` is replaced with the number of products shown.
`noResultsAnnouncement`	`no-results-announcement`	`string`	`No results`	Announced when there is a search term but nothing to show.

The BreadcrumbContent interface defines the structure for each item passed to the breadcrumbs property. Items are rendered by the Breadcrumb component without separators, capped at maxBreadcrumbs. Content placed in the breadcrumb slot replaces this default rendering.

Property	Type	Required	Description
`label`	`string`	Yes	The display text for the breadcrumb item. Also passed as the label in the nbhd-autosuggest-click event detail.
`href`	`string`	No	The URL the breadcrumb item links to. Items with an href render as a link and emit nbhd-autosuggest-click when clicked; items without one render as plain text and are not clickable.

Product Content Structure

The ProductCardContent interface defines the structure for individual product cards displayed in the autosuggest results. All properties are optional.

Property	Type	Required	Description
`href`	`string`	No	The URL the product card should link to.
`external`	`boolean`	No	Whether the link should open in a new tab/window.
`media`	`MediaContent`	No	The product's primary media.
`mediaAlternate`	`MediaContent`	No	The alternate media for the product.
`title`	`string`	No	The product title or name.
`identifier`	`string`	No	The product model number or identifier displayed with the product.
`identifierLabel`	`string`	No	The label displayed before the product identifier.
`noIdentifierLabel`	`boolean`	No	Whether to hide the label displayed before the product identifier.
`price`	`string`	No	The product price as a formatted string.
`badges`	`string[]`	No	Labels or badges associated with the product.
`productOptions`	`ProductOption[]`	No	Product option data associated with the product card.

Suggestion List Content Structure

The ListContent interface defines the structure for each suggestion list passed to the suggestions property and displayed in the autosuggest panel.

Property	Type	Required	Description
`title`	`string`	No	The suggestion list title or heading displayed above its items.
`items`	`ListItem[]`	Yes	Array of suggestion items within this list.

List Item Content Structure

The ListItem interface defines the structure for individual items within suggestion lists. Items with an href render as links and emit nbhd-autosuggest-click when clicked; items without an href render as plain text.

Property	Type	Required	Description
`label`	`string`	Yes	The display text for the suggestion item, also used as the label in the nbhd-autosuggest-click event detail.
`href`	`string`	No	The URL for the suggestion item. If omitted, the item is rendered as plain text; otherwise it renders as a link and emits nbhd-autosuggest-click when clicked.
`external`	`boolean`	No	Whether the suggestion link should open in a new tab/window. This applies only when href is provided.
`cssClass`	`string`	No	Additional CSS class passed to the suggestion link. This applies only when href is provided.

Events

Name	Description	Event Detail
`nbhd-autosuggest-see-more`	Bubbles when the 'See more results' button is clicked. The event is cancelable and composed.	`{ term: string }`
`nbhd-autosuggest-click`	Bubbles when a suggestion link, product card link, or breadcrumb link is clicked. The event is cancelable and composed.	`Suggestion link: { from: 'autosuggest', item: ListItem, term: string, label: string, originalEvent: Event }; product card: { from: 'autosuggest', product: ProductCardContent, term: string, label: string, originalEvent: Event }; breadcrumb: { from: 'autosuggest', term: string, label: string, href?: string, originalEvent: Event }`

Slots

Named slots allow custom content to replace the default breadcrumb, suggestion list, or product result rendering.

Name	Description
`breadcrumb`	Custom breadcrumb content. Replaces the default Breadcrumb component at the top of the autosuggest panel.
`suggestions`	Custom suggestion content. Replaces the default suggestion lists rendered from the suggestions property.
`results`	Custom results content. Replaces the default heading and product cards rendered from the products property. The See more results button remains outside this slot.

CSS Parts

Parts exposed by the autosuggest component for styling its layout, slots, breadcrumbs, suggestions, and results.

Name	Description
`base`	The component's base wrapper.
`container`	The main container element.
`wrapper`	The inner wrapper containing all content sections.
`breadcrumb-wrapper`	The wrapper around the breadcrumb section.
`breadcrumb-slot`	The named breadcrumb slot.
`breadcrumb`	The default Breadcrumb component.
`heading`	The search results heading displaying the heading text and search term.
`results`	The results section wrapper.
`results-slot`	The named results slot containing the default heading and product results.
`products`	The wrapper around the product results.
`product`	An individual product card in the results.
`suggestions`	The suggestions section wrapper.
`suggestions-slot`	The named suggestions slot containing the default suggestion lists.
`suggestions-wrapper`	The wrapper around the default suggestion lists.
`suggestion-list`	An individual suggestion list.
`suggestion-item`	An individual suggestion item, rendered as text or a link.

nbhd-autosuggest::part(base) {
  /* your styles */
}

CSS Properties

Set these on nbhd-autosuggest or an ancestor to override the defaults. Token is the design token a default comes from and Value is what it resolves to in core Neighborhood; brands may override them. Properties that adapt to surface follow the light or inverse surface they sit on until you set them.

Property	Token	Value
`--nbhd-autosuggest-breadcrumb-alignItems`	—	`start`
`--nbhd-autosuggest-breadcrumb-bpSm-flexDirection`	—	`row`
`--nbhd-autosuggest-breadcrumb-flexDirection`	—	`column`
`--nbhd-autosuggest-breadcrumb-item-fontWeight`	`--nbhd-typography-action-fontWeight`	`700`
`--nbhd-autosuggest-breadcrumb-paddingBlock`	`--nbhd-space-2`	`8px`
`--nbhd-autosuggest-breadcrumb-paddingInline`	`--nbhd-space-4`	`16px`
`--nbhd-autosuggest-display`	—	`block`
`--nbhd-autosuggest-inlineSize`	—	`100%`
`--nbhd-autosuggest-maxInlineSize`	—	`100%`
`--nbhd-autosuggest-results-bpLg-paddingInline`	`--nbhd-space-0 --nbhd-space-4`	`0px 16px`
`--nbhd-autosuggest-results-cta-inlineSize`	—	`100%`
`--nbhd-autosuggest-results-cta-marginBlock`	`--nbhd-space-2 --nbhd-space-0`	`8px 0px`
`--nbhd-autosuggest-results-heading-bpMd-marginBlock`	`--nbhd-space-0`	`0px`
`--nbhd-autosuggest-results-heading-marginBlock`	`--nbhd-space-2 0`	`8px 0`
`--nbhd-autosuggest-results-heading-paddingInline`	`--nbhd-space-0`	`0px`
`--nbhd-autosuggest-results-paddingInline`	`--nbhd-space-0`	`0px`
`--nbhd-autosuggest-results-products-bpLg-gridTemplateColumns`	—	`repeat(4, .25fr)`
`--nbhd-autosuggest-results-products-bpSm-gridTemplateColumns`	—	`repeat(3, .33fr)`
`--nbhd-autosuggest-results-products-display`	—	`grid`
`--nbhd-autosuggest-results-products-gap`	`--nbhd-space-1`	`4px`
`--nbhd-autosuggest-results-products-gridTemplateColumns`	—	`repeat(2, .5fr)`
`--nbhd-autosuggest-results-products-justifyContent`	—	`center`
`--nbhd-autosuggest-results-products-justifyItems`	—	`center`
`--nbhd-autosuggest-suggestions-bpMd-display`	—	`block`
`--nbhd-autosuggest-suggestions-display`	—	`none`
`--nbhd-autosuggest-suggestions-item-fontWeight`	`--nbhd-typography-action-fontWeight`	`700`
`--nbhd-autosuggest-suggestions-item-marginBlock`	`--nbhd-space-0 --nbhd-space-05`	`0px 2px`
`--nbhd-autosuggest-suggestions-paddingInline`	`--nbhd-space-4 --nbhd-space-0`	`16px 0px`
`--nbhd-autosuggest-wrapper-bpMd-gap`	`--nbhd-space-5`	`20px`
`--nbhd-autosuggest-wrapper-breadcrumbs-paddingBlock`	`--nbhd-space-0 --nbhd-space-4`	`0px 16px`
`--nbhd-autosuggest-wrapper-gap`	`--nbhd-space-4`	`16px`
`--nbhd-autosuggest-wrapper-gridTemplateAreas`	—	`"breadcrumbs" "suggestions" "results"`
`--nbhd-autosuggest-wrapper-gridTemplateColumns`	—	`1fr`
`--nbhd-autosuggest-wrapper-paddingBlock`	`--nbhd-space-4`	`16px`

Dependencies

Child components <nbhd-autosuggest> renders internally. Import them too when you tree-shake.

TextReady <nbhd-text> ButtonReady <nbhd-button> BreadcrumbReady <nbhd-breadcrumb> ListReady <nbhd-list> Product CardReady <nbhd-product-card>

Preview

Code

Usage

Properties

Breadcrumb Content Structure

Product Content Structure

Suggestion List Content Structure

List Item Content Structure

Events

Slots

CSS Parts

CSS Properties

Dependencies