{"id":25793865,"url":"https://github.com/constructor-io/constructorio-ui-autocomplete","last_synced_at":"2026-01-28T20:28:30.849Z","repository":{"id":65617597,"uuid":"539737932","full_name":"Constructor-io/constructorio-ui-autocomplete","owner":"Constructor-io","description":"Constructor.io Autocomplete UI library for web applications","archived":false,"fork":false,"pushed_at":"2025-02-12T19:38:03.000Z","size":16688,"stargazers_count":13,"open_issues_count":2,"forks_count":1,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-02-20T09:03:10.026Z","etag":null,"topics":["autocomplete","autosuggest","constructorio-integrations","javascript","react","react-hooks","typescript"],"latest_commit_sha":null,"homepage":"https://constructor-io.github.io/constructorio-ui-autocomplete","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Constructor-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-22T00:43:43.000Z","updated_at":"2025-02-12T19:34:28.000Z","dependencies_parsed_at":"2024-01-02T16:24:38.328Z","dependency_job_id":"73a0177a-8702-45e3-a83d-8c00fab29a1b","html_url":"https://github.com/Constructor-io/constructorio-ui-autocomplete","commit_stats":{"total_commits":97,"total_committers":13,"mean_commits":7.461538461538462,"dds":0.5360824742268041,"last_synced_commit":"c7ab6265806b2e3890a278dd7f23bba26c5acc81"},"previous_names":[],"tags_count":105,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-ui-autocomplete","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-ui-autocomplete/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-ui-autocomplete/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-ui-autocomplete/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Constructor-io","download_url":"https://codeload.github.com/Constructor-io/constructorio-ui-autocomplete/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241019405,"owners_count":19895245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autocomplete","autosuggest","constructorio-integrations","javascript","react","react-hooks","typescript"],"created_at":"2025-02-27T13:41:01.650Z","updated_at":"2026-01-28T20:28:30.842Z","avatar_url":"https://github.com/Constructor-io.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Autocomplete UI\nLightweight, minimalistic, and fully customizable autocomplete component for fast, accessible, and flexible search experiences with [Constructor.io's autosuggest services](https://constructor.com/solutions/search)\n\n![minzipped size](https://img.shields.io/bundlephobia/minzip/@constructor-io/constructorio-ui-autocomplete?color=green\u0026style=flat-square)\n[![NPM Version](https://img.shields.io/npm/v/@constructor-io/constructorio-ui-autocomplete?style=flat-square)](https://www.npmjs.com/package/@constructor-io/constructorio-ui-autocomplete)\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/Constructor-io/constructorio-ui-autocomplete/blob/main/LICENSE)\n\n![Autocomplete UI Demonstration](assets/autocomplete-ui-demonstration.gif)\n\n## Documentation\n\nView the full component documentation and live examples in [Storybook](https://constructor-io.github.io/constructorio-ui-autocomplete/?path=/docs/autocomplete-component--docs)\n\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n## 📌 Table of Contents\n\n- [Overview](#overview)\n- [Installation \u0026 Quick Start](#installation--quick-start)\n  - [Basic Usage (React)](#basic-usage-react)\n- [Integration Modes](#integration-modes)\n  - [Shopify](#shopify)\n    - [Installation \u0026 Quick Start](#installation--quick-start-1)\n    - [🛍️ Shopify-Specific Defaults](#-shopify-specific-defaults)\n- [Bundle (Vanilla JS)](#bundle-vanilla-js)\n    - [Installation \u0026 Quick Start](#installation--quick-start-2)\n- [Customization](#customization)\n- [Troubleshooting](#troubleshooting)\n- [Complementary Resources](#complementary-resources)\n- [Contributing](#contributing)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\n## Overview\n\nAutocomplete UI provides a lightweight and customizable autocomplete component. It enables developers to quickly implement fast, accessible search experiences with Constructor.io's autosuggest services.\n\n- 🔌 Easy Integration – Quickly integrate with your app as a plug-and-play React component\n- ⚡ Lightweight \u0026 Fast – Tiny bundle size, optimized for speed\n- 🎨 Customizable UI – With minimal styles, and supports for custom markup\n- ⌨️ Keyboard Navigation – Fully supports accessible keyboard navigation\n- ♿ Accessible (a11y) – Built-in ARIA support for screen readers\n- 🛡 Written in TypeScript with type safety\n\n**[Explore full documentation →](https://constructor-io.github.io/constructorio-ui-autocomplete/?path=/docs/autocomplete-component--docs)**\n\n## Installation \u0026 Quick Start\n\nInstall the library\n\n```sh\nnpm i @constructor-io/constructorio-ui-autocomplete\n```\n\n### Basic Usage (React)\nImport and use the `CioAutocomplete` component\n\n```tsx\nimport { CioAutocomplete } from '@constructor-io/constructorio-ui-autocomplete';\nimport '@constructor-io/constructorio-ui-autocomplete/styles.css';\n\nfunction YourComponent() {\n  return (\n    \u003cdiv\u003e\n      \u003cCioAutocomplete\n        apiKey=\"key_M57QS8SMPdLdLx4x\"\n        onSubmit={(e) =\u003e {console.log(e)}}\n      /\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## Integration Modes\n\n### Shopify\n\n#### Installation \u0026 Quick Start\n\nThe Constructor autocomplete component is available as part of the [Constructor.io Shopify App](https://apps.shopify.com/constructor-connect)\n\nAfter 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\n\n![installation gif](./assets/autocomplete-ui-liquid-shopify-demo.gif)\n\nFor more in depth instructions, check out the [Shopify documentation](https://docs.constructor.com/docs/integrating-with-constructor-platform-connectors-frontend-connectors-shopify-ui).\n\n#### 🛍️ Shopify-Specific Defaults\n\nIf you are using the Constructor autocomplete component inside Shopify without using the [Constructor.io Shopify App](https://apps.shopify.com/constructor-connect), you can use  the `useShopifyDefaults` prop to enable automatic navigation handling:\n\n```tsx\n\u003cCioAutocomplete\n  apiKey=\"your-api-key\"\n  useShopifyDefaults={true}\n  shopifySettings={{ searchUrl: '/search' }}\n/\u003e\n```\n\n**What it does:**\n- **Product selections**: Automatically redirects to the product detail page\n- **Search suggestions**: Redirects to the search results page with the selected query\n- **Manual search**: Redirects to the search results page with the entered query\n- **Query parameters**: Preserves all existing URL query parameters (e.g., UTM parameters)\n\n**Configuration:**\n- `shopifySettings.searchUrl`: The search results page URL (e.g: `'{{ block.settings.search_url }}'` for Liquid templates)\n\n**Note:** When `useShopifyDefaults={true}`, any custom `onSubmit` handler you provide will override the default behavior.\n\n## Bundle (Vanilla JS)\nThis 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.\n\n#### Installation \u0026 Quick Start\n\nInstall the library\n\n```sh\nnpm i @constructor-io/constructorio-ui-autocomplete\n```\n\nImport and use the `CioAutocomplete` component\n```javascript\nimport CioAutocomplete from '@constructor-io/constructorio-ui-autocomplete/constructorio-ui-autocomplete-bundled';\n\nCioAutocomplete({\n  selector: '#autocomplete-container',\n  includeCSS: true, // Include the default CSS styles. Defaults to true.\n  apiKey: 'key_M57QS8SMPdLdLx4x',\n  onSubmit: (submitEvent) =\u003e console.dir(submitEvent),\n  // ... additional arguments\n});\n\u003c/script\u003e\n```\n\n## Customization\n\nCSS styles are not imported by default. Add this to your code to import basic styles\n\n```tsx\nimport '@constructor-io/constructorio-ui-autocomplete/styles.css';\n```\n\nAll styles are scoped under .cio-autocomplete. You can extend them by targeting that selector.\n\n```css\n/* Custom Style Sheet */\n.cio-autocomplete .cio-submit-btn {\n  border-radius: 10px;\n  border: 1px solid red;\n}\n```\n\nIf you'd like to override or extend the base `className`, you can do so with the `autocompleteClassName` argument\n\n```tsx\nimport { CioAutocomplete } from '@constructor-io/constructorio-ui-autocomplete';\nimport '@constructor-io/constructorio-ui-autocomplete/styles.css';\n\nfunction YourComponent() {\n  return (\n    \u003cdiv\u003e\n      \u003cCioAutocomplete\n        apiKey=\"key_M57QS8SMPdLdLx4x\"\n        onSubmit={(e) =\u003e { console.log(e)}}\n        autocompleteClassName=\"cio-autocomplete custom-autocomplete-container\"\n      /\u003e\n    \u003c/div\u003e\n  );\n```\n\nThen you can modify styles like so\n\n```css\n/* Custom Style Sheet */\n.cio-autocomplete.custom-autocomplete-styles .cio-input {\n  font-weight: bold;\n}\n```\n\n## Troubleshooting\n\nCommon issues and solutions.\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003eProblem\u003c/th\u003e\n      \u003cth\u003eDescription\u003c/th\u003e\n      \u003cth\u003eSolution\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n      \u003ctr\u003e\n          \u003ctd\u003eOlder JavaScript environments\u003c/td\u003e\n          \u003ctd\u003e\n            The library provides two different builds. CommonJS (cjs) and ECMAScript Modules (mjs)\n            \u003cbr\u003e\n            \u003cbr\u003e\n            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.\n            \u003cbr\u003e\n            \u003cbr\u003e\n            \u003ccode\u003eModule 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\u003c/code\u003e\n          \u003c/td\u003e\n          \u003ctd\u003e\n            To solve this you can import the CommonJS (cjs) build which supports ES6 (ES2015) syntax:\n            \u003cbr\u003e\n            \u003cbr\u003e\n            \u003ccode\u003eimport CioAutocomplete from '@constructor-io/constructorio-ui-autocomplete/cjs'\u003c/code\u003e\n          \u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n        \u003ctd\u003eESLint\u003c/td\u003e\n        \u003ctd\u003e\n          There is a known issue with ESLint where it fails to resolve the paths exposed in the exports statement of NPM packages.\n          \u003cbr\u003e\n          \u003cbr\u003e\n          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.\n          \u003cbr\u003e\n          \u003cbr\u003e\n          \u003ccode\u003eUnable to resolve path to module '@constructor-io/constructorio-ui-autocomplete/styles.css'\u003c/code\u003e\n          \u003cbr\u003e\n          \u003cbr\u003e\n          Relevant open issues:\n          \u003cul\u003e\n            \u003cli\u003e\u003ca href='https://github.com/import-js/eslint-plugin-import/issues/1868'\u003eIssue 1868\u003c/a\u003e\n            \u003cli\u003e\u003ca href='https://github.com/import-js/eslint-plugin-import/issues/1810'\u003eIssue 1810\u003c/a\u003e\n        \u003c/td\u003e\n        \u003ctd\u003e\n          If you are receiving the following error, you can safely disable ESLint using \u003ccode\u003e// eslint-disable-line\u003c/code\u003e for that line.\n        \u003c/td\u003e\n      \u003c/tr\u003e\n      \u003ctr\u003e\n        \u003ctd\u003ePeer Dependencies\u003c/td\u003e\n        \u003ctd\u003e\n          The library requires a couple of peer dependencies to be installed, so ensure they're installed if not already.\n          \u003cbr /\u003e\n          \u003cbr /\u003e\n          \u003col\u003e\n            \u003cli\u003e\u003ca href=\"https://github.com/Constructor-io/constructorio-client-javascript\"\u003econstructorio-client-javascript\u003c/a\u003e\u003c/li\u003e\n            \u003cli\u003e\u003ca href=\"https://github.com/downshift-js/downshift\"\u003edownshift\u003c/a\u003e\u003c/li\u003e\n          \u003c/ol\u003e\n        \u003c/td\u003e\n        \u003ctd\u003e\n          Run \u003ccode\u003enpm i downshift @constructor-io/constructorio-client-javascript\u003c/code\u003e\n        \u003c/td\u003e\n      \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n💬 Need help? Join our [GitHub Discussions](https://github.com/Constructor-io/constructorio-ui-autocomplete/discussions)\n\n## Complementary Resources\n\n- 📖 Full Documentation: [Storybook](https://constructor-io.github.io/constructorio-ui-autocomplete/)\n- 📦 JS Client: [SDK Documentation](https://constructor-io.github.io/constructorio-client-javascript/module-autocomplete.html#~getAutocompleteResults)\n- 🛒 Shopify App: [App Store Link](https://apps.shopify.com/constructor-connect)\n- 🌐 Constructor's REST API: [Autocomplete](https://docs.constructor.com/reference/v1-autocomplete-get-autocomplete-results)\n\n## Contributing\n\n1. Fork the repo \u0026 create a new branch.\n2. Run `npm install` to install dependencies.\n3. After making the desired changes, run `npm run tests \u0026\u0026 npm run lint` locally.\n4. Submit a PR for review.\n\n## License\n\n[MIT License](./LICENSE)\n\nCopyright (c) 2022-present Constructor.io Corporation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructor-io%2Fconstructorio-ui-autocomplete","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconstructor-io%2Fconstructorio-ui-autocomplete","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructor-io%2Fconstructorio-ui-autocomplete/lists"}