Bloomreach Limitless UI

Introduction

Bloomreach Limitless UI is a React library for integrating Bloomreach Search's search and merchandising capabilities into your application. It provides a set of customizable React components and hooks that work seamlessly with the Bloomreach Discovery Web SDK.

Key features:

• Multiple integration levels, from low-level SDK access to high-level components
• React hooks for efficient state management
• Headless components for maximum customization
• Accessibility-focused design
• Performance-optimized

Storybook

For a showcase of all available components, hooks, and their props, refer to our Storybook documentation.

Installation

Install the Bloomreach Limitless UI React package @bloomreach/limitless-ui-react using npm, yarn, or pnpm:

npm install @bloomreach/limitless-ui-react

yarn add @bloomreach/limitless-ui-react

pnpm add @bloomreach/limitless-ui-react

Core concepts

Integration levels

Bloomreach Limitless UI React offers multiple integration levels to suit different needs:

• Web SDK direct usage: Use the @bloomreach/discovery-web-sdk directly for full control over API calls.
• Context-aware hooks: Use hooks like useSearchBox to interact with the library's context system.
• Headless components: Implement accessible, unstyled components (e.g., <SearchBox />) for a balance of functionality and customization.
• Styled components: Include an optional styling bundle for a complete out-of-the-box experience.

Compound components

Limitless UI React uses the compound component pattern for complex components like SearchBox. This pattern provides more flexibility and control over component composition. For example:

<SearchBox.Root configuration={configuration} searchOptions={searchOptions} searchType="product">
  <SearchBox.Suggestions suggestOptions={suggestOptions} />
</SearchBox.Root>

This pattern allows you to:

• Compose components with flexibility
• Control exactly which subcomponents to include
• Maintain a clear hierarchy of related components

Components and hooks

Each major feature in Limitless UI React is represented by a component and corresponding hooks. This design allows for flexible usage depending on your specific needs.

Getting started

Prerequisites

• Node.js (version 20 or higher)
• React (version 18.3.1 or higher)
• @bloomreach/discovery-web-sdk (version 1.2.1 or higher)

Basic setup

1. Set up the Limitless UI provider in your main App component:

import { LimitlessUIProvider } from '@bloomreach/limitless-ui-react';

const App = () => {
  return <LimitlessUIProvider>{/* Your app components */}</LimitlessUIProvider>;
};

export default App;

2. Use Limitless UI React components in your application:

import { SearchBox } from '@bloomreach/limitless-ui-react';

const SearchPage = () => {
  return (
    <div>
      <SearchBox.Root
        configuration={configuration}
        searchOptions={searchOptions}
        searchType="product"
      />

      <Results resultComponent={(result) => <div>{result.title}</div>} />
    </div>
  );
};

export default SearchPage;

Usage examples

Using the Web SDK directly

For direct SDK usage, refer to the Bloomreach Discovery Web SDK documentation.

Using the API hooks

The API level hooks like useSearch provide a low-level interface to retrieve API results and register them within React state:

import { useSearch } from '@bloomreach/limitless-ui-react';

const SearchComponent = ({ query, configuration, searchOptions }) => {
  const { response, loading, error } = useSearch('product', query, configuration, searchOptions);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {response && response.response.docs.map((item) => <div key={item.id}>{item.title}</div>)}
    </div>
  );
};

Using component hooks

The component hooks like useSearchBox provide a higher-level interface that also interacts with the context and outputs state and handlers to build your own custom component:

import { useSearchBox, SearchContext } from '@bloomreach/limitless-ui-react';

const CustomSearchBox = (props) => {
  const { response, loading, error, changeHandler, submitHandler, resetHandler, inputValue } =
    useSearchBox(props);

  return (
    <>
      <form onSubmit={submitHandler} onReset={resetHandler}>
        <input type="text" value={inputValue} onChange={changeHandler} placeholder="Search..." />
        <button type="submit">Search</button>
        <button type="reset">Clear</button>
      </form>

      <Results
        resultComponent={(result) => (
          <div key={result.pid}>
            <h2>{result.title}</h2>
            <p>{result.description}</p>
          </div>
        )}
      />
    </>
  );
};

Using components

Components like SearchBox use a compound pattern that provides both flexibility and structure:

import { SearchBox } from '@bloomreach/limitless-ui-react';

const SearchPage = () => {
  return (
    <div>
      <SearchBox.Root
        configuration={/* your configuration */}
        searchOptions={/* your search options */}
        searchType="product"
        labels={{
          placeholder: "Search products...",
          submit: "Search",
          reset: "Clear"
        }}
      >
        <SearchBox.Suggestions
          suggestOptions={/* your suggestion options */}
          onQuerySelect={(query, event) => {
            // Handle query selection
          }}
          onSearchSelect={(product, event) => {
            // Handle product selection
          }}
        />
      </SearchBox.Root>
    </div>
  );
};

Using components with the style bundle

Combine the headless components with the optional style bundle for a full out-of-the-box experience. Import style.css from the package in your project's preferred way.

Customize styling

You can add styling to specific classes used in the component templates, like <SearchBox>. A set of CSS properties, such as --lui-search-box-min-height, are also available and can be set to a different value than their defaults.

Troubleshoot common issues

If you encounter issues:

1. Ensure all dependencies are up to date.
2. Check the console for error messages.
3. Verify your account credentials (accountId, domainKey, authKey).
4. Review the Bloomreach Discovery Web SDK documentation for SDK-specific issues.

If problems persist, open an issue on our GitHub repository.

Contribute to this project

Read our Contributing Guidelines for information on how to get started.

Changes

See our Changelog for the full list of releases and their changes.

License

Bloomreach Limitless UI React is licensed under the MIT License.

Support

For support, open an issue on our GitHub repository or contact our support team.