Autocomplete UI

Lightweight, minimalistic, and fully customizable autocomplete component for fast, accessible, and flexible search experiences with Constructor.io's autosuggest services

Documentation

View the full component documentation and live examples in Storybook

📌 Table of Contents

• Overview
• Installation & Quick Start
  • Basic Usage (React)
• Integration Modes
  • Shopify
    • Installation & Quick Start
    • 🛍️ Shopify-Specific Defaults
• Bundle (Vanilla JS)
  • Installation & Quick Start
• Customization
• Troubleshooting
• Complementary Resources
• Contributing
• License

Overview

Autocomplete UI provides a lightweight and customizable autocomplete component. It enables developers to quickly implement fast, accessible search experiences with Constructor.io's autosuggest services.

• 🔌 Easy Integration – Quickly integrate with your app as a plug-and-play React component
• ⚡ Lightweight & Fast – Tiny bundle size, optimized for speed
• 🎨 Customizable UI – With minimal styles, and supports for custom markup
• ⌨️ Keyboard Navigation – Fully supports accessible keyboard navigation
• ♿ Accessible (a11y) – Built-in ARIA support for screen readers
• 🛡 Written in TypeScript with type safety

Explore full documentation →

Installation & Quick Start

Install the library

npm i @constructor-io/constructorio-ui-autocomplete

Basic Usage (React)

Import and use the CioAutocomplete component

import { CioAutocomplete } from '@constructor-io/constructorio-ui-autocomplete';
import '@constructor-io/constructorio-ui-autocomplete/styles.css';

function YourComponent() {
  return (
    <div>
      <CioAutocomplete
        apiKey="key_M57QS8SMPdLdLx4x"
        onSubmit={(e) => {console.log(e)}}
      />
    </div>
  );
}

Integration Modes

Shopify

Installation & Quick Start

The Constructor autocomplete component is available as part of the Constructor.io Shopify App

After installing the app, you can use the Constructor autocomplete component by clicking 'Add Section' in your theme editor and adding the Constructor autocomplete liquid component

For more in depth instructions, check out the Shopify documentation.

🛍️ Shopify-Specific Defaults

If you are using the Constructor autocomplete component inside Shopify without using the Constructor.io Shopify App, you can use the useShopifyDefaults prop to enable automatic navigation handling:

<CioAutocomplete
  apiKey="your-api-key"
  useShopifyDefaults={true}
  shopifySettings={{ searchUrl: '/search' }}
/>

What it does:

• Product selections: Automatically redirects to the product detail page
• Search suggestions: Redirects to the search results page with the selected query
• Manual search: Redirects to the search results page with the entered query
• Query parameters: Preserves all existing URL query parameters (e.g., UTM parameters)

Configuration:

• shopifySettings.searchUrl: The search results page URL (e.g: '{{ block.settings.search_url }}' for Liquid templates)

Note: When useShopifyDefaults={true}, any custom onSubmit handler you provide will override the default behavior.

Bundle (Vanilla JS)

This is a framework agnostic method that can be used in any JavaScript project. The CioAutocomplete function provides a simple interface to inject an entire Autocomplete UI into the provided selector. In addition to Autocomplete component props, this function also accepts a selector and includeCSS.

Installation & Quick Start

Install the library

npm i @constructor-io/constructorio-ui-autocomplete

Import and use the CioAutocomplete component

import CioAutocomplete from '@constructor-io/constructorio-ui-autocomplete/constructorio-ui-autocomplete-bundled';

CioAutocomplete({
  selector: '#autocomplete-container',
  includeCSS: true, // Include the default CSS styles. Defaults to true.
  apiKey: 'key_M57QS8SMPdLdLx4x',
  onSubmit: (submitEvent) => console.dir(submitEvent),
  // ... additional arguments
});
</script>

Customization

CSS styles are not imported by default. Add this to your code to import basic styles

import '@constructor-io/constructorio-ui-autocomplete/styles.css';

All styles are scoped under .cio-autocomplete. You can extend them by targeting that selector.

/* Custom Style Sheet */
.cio-autocomplete .cio-submit-btn {
  border-radius: 10px;
  border: 1px solid red;
}

If you'd like to override or extend the base className, you can do so with the autocompleteClassName argument

import { CioAutocomplete } from '@constructor-io/constructorio-ui-autocomplete';
import '@constructor-io/constructorio-ui-autocomplete/styles.css';

function YourComponent() {
  return (
    <div>
      <CioAutocomplete
        apiKey="key_M57QS8SMPdLdLx4x"
        onSubmit={(e) => { console.log(e)}}
        autocompleteClassName="cio-autocomplete custom-autocomplete-container"
      />
    </div>
  );

Then you can modify styles like so

/* Custom Style Sheet */
.cio-autocomplete.custom-autocomplete-styles .cio-input {
  font-weight: bold;
}

Troubleshooting

Common issues and solutions.

Problem	Description	Solution
Older JavaScript environments	The library provides two different builds. CommonJS (cjs) and ECMAScript Modules (mjs) For ECMAScript Modules (mjs) build, the JavaScript version is ESNext which might not be supported by your environment. If that's the case and your environment is using an older Javascript version like ES6 (ES2015), you might get this error. Module parse failed: Unexpected token (15:32) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file	To solve this you can import the CommonJS (cjs) build which supports ES6 (ES2015) syntax: import CioAutocomplete from '@constructor-io/constructorio-ui-autocomplete/cjs'
ESLint	There is a known issue with ESLint where it fails to resolve the paths exposed in the exports statement of NPM packages. For ECMAScript Modules (mjs) build. The Javascript version is ESNext which might not be supported by your environment. If that's the case and your environment is using an older Javascript version like ES6 (ES2015), you might get this error. Unable to resolve path to module '@constructor-io/constructorio-ui-autocomplete/styles.css' Relevant open issues: Issue 1868 Issue 1810	If you are receiving the following error, you can safely disable ESLint using // eslint-disable-line for that line.
Peer Dependencies	The library requires a couple of peer dependencies to be installed, so ensure they're installed if not already. constructorio-client-javascript downshift	Run npm i downshift @constructor-io/constructorio-client-javascript

💬 Need help? Join our GitHub Discussions

Complementary Resources

• 📖 Full Documentation: Storybook
• 📦 JS Client: SDK Documentation
• 🛒 Shopify App: App Store Link
• 🌐 Constructor's REST API: Autocomplete

Contributing

1. Fork the repo & create a new branch.
2. Run npm install to install dependencies.
3. After making the desired changes, run npm run tests && npm run lint locally.
4. Submit a PR for review.

License

MIT License

Copyright (c) 2022-present Constructor.io Corporation