@constructor-io/constructorio-ui-autocomplete

Constructor.io Autocomplete UI Library

Introduction

This UI Library provides React components that manage fetching and rendering logic for Constructor.io's autosuggest services.

Our storybook docs are the best place to explore the behavior and configuration options for this UI Library.

How to use this UI Library

There are two main methods for consuming this UI Library in a React project:

Component based

The CioAutocomplete component handles state management, data fetching, and rendering logic.

import { CioAutocomplete } from 'constructorio-ui-autocomplete';

function YourComponent() {
  return (
    <div>
      <CioAutocomplete apiKey="key_Gep3oQOu5IMcNh9A" />
    </div>
  );

Hook based

The useCioAutocomplete hook handles state management and data fetching, but leaves rendering logic up to you.

import { useCioAutocomplete } from 'constructorio-ui-autocomplete';

function YourComponent() {
  const {
    isOpen,
    sections,
    getFormProps,
    getLabelProps,
    getInputProps,
    getMenuProps,
    getItemProps,
    autocompleteClassName
  } = useCioAutocomplete(args);

  return (
    <div className={autocompleteClassName}>
      <form {...getFormProps()}>
        <label {...getLabelProps()} hidden>
          Search
        </label>
        <input {...getInputProps()} />
      </form>
      <div {...getMenuProps()}>
        {isOpen && (
          <>
            {sections?.map((section) => (
              <div key={section.identifier} className={section.identifier}>
                <div className='cio-section'>
                  <div className='cio-sectionName'>
                    {section?.displayName || section.identifier}
                  </div>
                  <div className='cio-items'>
                    {section?.data?.map((item, index) => (
                      <div
                        {...getItemProps({
                          item,
                          index,
                          sectionIdentifier: section.identifier
                        })}
                        key={item?.data?.id}>
                        <div>
                          {isProduct(item) && (
                            <img
                              width='100%'
                              src={item.data?.image_url}
                              alt=''
                              data-testid='cio-img'
                            />
                          )}
                          <p>{item.value}</p>
                        </div>
                      </div>
                    ))}
                  </div>
                </div>
              </div>
            ))}
          </>
        )}
      </div>
    </div>
  );
}

Custom Styling

Library defaults

By default, importing react components or hooks from this library does not pull any css into your project.

If you wish to use some starter styles from this library, add an import statement similar to the example import statement below:

import 'node_modules/@constructor-io/constructorio-ui-autocomplete/lib/mjs/components/Autocomplete/Autocomplete.css';

Note: the path and syntax in this example may change slightly depending on your module bundling strategy

• These starter styles can be used as a foundation to build on top of, or just as a reference for you to replace completely.
• To opt out of all default styling, do not import the Autocomplete.css stylesheet.
• All starter styles in this library are scoped within the .cio-autocomplete css selector.
• These starter styles are intended to be extended by layering in your own css rules
• If you like, you can override the container's className like so: autocompleteClassName='custom-autocomplete-container'
• If you like, you can pass additional className(s) of your choosing like so: autocompleteClassName='cio-autocomplete custom-autocomplete-container'

Local Development

Development scripts

npm ci                  # install dependencies for local dev
npm run dev             # start a local dev server for Storybook
npm run lint            # run linter

Maintain Library

npm run compile           # generate lib folder for publishing to npm
npm run build-storybook   # generate storybook static bundle for deploy with GH Pages

Supporting Docs

• Storybook 7 Introduction
• Typescript Docs