React components

@orbsearch/react draws a storefront in React 19.3 or a later React 19: the search box, a page for every listing, a product page and the parts they are made of. It brings the behavior, the semantics and a plain look, and reads every answer through the client:

import { createSearch, isListing, type PageResponse } from "@orbsearch/client";
import { ListingPage, ProductPage, StorefrontProvider, listingView } from "@orbsearch/react";
import type { ReactNode } from "react";

const search = createSearch({ endpoint: "http://127.0.0.1:7800" });

export function Storefront({ children }: { children: ReactNode }) {
    return (
        <StorefrontProvider search={search} locale="de">
            {children}
        </StorefrontProvider>
    );
}

export function Page({ page, path }: { page: PageResponse; path: string }) {
    if (isListing(page)) return <ListingPage listing={listingView(page, { path, locale: "de" })} />;
    if (page.product) return <ProductPage product={page.product} trail={[{ title: page.product.title, href: path }]} />;
    return null;
}

StorefrontProvider holds the client, the language and your router's navigate; without one, a link loads the next page. page is what resolve answered, and listingView reads a listing out of it. Your storefront is the whole shop in React Router.

The two pagesCopy Anchor Link

ListingPage draws a search, category or brand page from listing, the view listingView reads out of resolve's answer. It takes a few props beside it:

• filters: "bar", the default, for quick filters above the results and all of them in a sheet, or "sidebar" for a panel beside the results.
• tile and banner: your own, built from the parts (Customize).
• sorts: the sort codes to offer instead of the answer's, the first where the page starts.
• sectionTitle, departments and tip: the heading of a section beside the products, where an empty search sends the shopper, and your advice when nothing is found.
• busy: your router says the next page is on its way, as useNavigation does.

What only your shop knows is empty in the view and yours to set, as { ...view, trail, categories, popular }: your home in the trail, your category navigation and the products an empty search offers.

ProductPage takes the product and its trail, the categories from the top down with the product last. variant is the variant the URL names, read with variantAt(product, url)?.id; more adds a rail of other products, and buyBox replaces the part a shopper decides on.

The partsCopy Anchor Link

Each block of the pages is a part with one job, exported on its own for a layout of your own:

Hooks sit below them: useListing holds a listing's state, useFacet one facet's values and semantics, useFilters a pending choice with its count, and useLiveFilters a choice that applies after a short pause.

Change an elementCopy Anchor Link

To change a part's element or classes and keep its semantics, use Base UI's render prop:

<ProductTile.Price render={(props) => <p {...props} className="shop-price" />} />;

Root, SponsoredLabel, Media, Badges, Badge, Brand, Price and Facts take render; Title, Image and Rating take a className. The search box takes groups to reorder or add groups of suggestions, and suggestion for a row of your own built on SuggestionItem. To change what a part holds, swap it.

Every ad is markedCopy Anchor Link

A product a sponsored pin placed starts its name with "Anzeige" (ad) or "Sponsored", messages.sponsored, so the tile marks the ad where its name is seen and read. Restyle the label through the title:

<ProductTile.Title label={<ProductTile.SponsoredLabel className="shop-ad" />} />;

To show it elsewhere in the tile, pass label={null} and place <ProductTile.SponsoredLabel /> yourself, since the law wants every ad marked. A suggestion row of your own renders <SuggestionSponsoredLabel suggestion={suggestion} /> before the name.

Facet displaysCopy Anchor Link

One registry of displays draws every facet, keyed by name, in the bar, the panel, the sheet and a layout of your own. Ours are exported as facetDisplays: list, stars, images, swatch, grades, buttons, select, range, slider, histogram, hierarchy and toggle.

A facet gets the display its release names in custom_display, else the one display names, else its kind's own. The shop's displays, passed to StorefrontProvider as displays, come before ours, so a storefront without yours still draws the facet as display says. A group of facets draws from groupDisplays, where ours is finder. Customize builds a display of your own.

Reference: custom_display · display

Facets that load when openedCopy Anchor Link

The Query API counts a page's first 30 facets and lists the rest as deferred, and cuts a long list to 50 values with more, since every counted facet costs the engine on each request. ListingPage wraps its parts in LateFacets, so the rest arrive when a shopper wants them:

import { FacetList, LateFacets, useListing, type ListingView } from "@orbsearch/react";

export function Facets({ listing }: { listing: ListingView }) {
    const page = useListing(listing);

    return (
        <LateFacets request={{ ...page.count, filters: page.filters }}>
            <FacetList facets={listing.facets} value={page.value} onChange={page.apply} />
        </LateFacets>
    );
}

A facet the shopper opens, or whose "Show more" they press, asks for its values with search.facets, under the choices the page shows, and again when they change. Meanwhile it says "Loading values …", or that they could not be loaded. A facet in a popover of your own calls useLoadWhenOpen. Without LateFacets, facets draw as given.

Reference: deferred · more · counted_facets

Words and photosCopy Anchor Link

The components speak German for de and its regions and English for every other locale. Pass your own messages to change a word or add a language, and images to load photos through your image host's widths:

import type { Search } from "@orbsearch/client";
import { messagesFor, StorefrontProvider, type ImageHost } from "@orbsearch/react";
import type { ReactNode } from "react";

const messages = { ...messagesFor("de"), searchPlaceholder: "Sofas, Teppiche, Leuchten" };
const images: ImageHost = { widths: [320, 640, 1024], url: (src, width) => `${src}?w=${width}` };

export function Storefront({ search, children }: { search: Search; children: ReactNode }) {
    return (
        <StorefrontProvider search={search} locale="de" messages={messages} images={images}>
            {children}
        </StorefrontProvider>
    );
}

The placeholder lists sofas, rugs and lights. Without images, photos load at the size the catalog's URL gives, and nouns names in your words the types a listing counts.

NextCopy Anchor Link

• Customize: tokens, slots, swapped parts and components of your own.
• Recipes: one facet in a layout of your own, filters in a sheet on a phone.
• Accessibility: what the components do for keyboard and screen reader users.