{"id":26103306,"url":"https://github.com/constructor-io/constructorio-ui-plp","last_synced_at":"2026-04-13T16:01:11.202Z","repository":{"id":255709293,"uuid":"683121300","full_name":"Constructor-io/constructorio-ui-plp","owner":"Constructor-io","description":"Constructor.io Product Listing Pages (PLP) UI library for web applications","archived":false,"fork":false,"pushed_at":"2026-04-08T12:07:47.000Z","size":6172,"stargazers_count":3,"open_issues_count":17,"forks_count":2,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-04-08T14:25:10.046Z","etag":null,"topics":["constructorio-integrations","javascript","react","react-hooks","typescript"],"latest_commit_sha":null,"homepage":"https://constructor-io.github.io/constructorio-ui-plp/","language":"JavaScript","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-25T16:45:21.000Z","updated_at":"2026-04-08T12:06:32.000Z","dependencies_parsed_at":"2024-10-24T21:36:59.440Z","dependency_job_id":"2fa747a0-9fe4-4e1d-9bd7-613a0f1ad66e","html_url":"https://github.com/Constructor-io/constructorio-ui-plp","commit_stats":null,"previous_names":["constructor-io/constructorio-ui-plp"],"tags_count":57,"template":false,"template_full_name":null,"purl":"pkg:github/Constructor-io/constructorio-ui-plp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-ui-plp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-ui-plp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-ui-plp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-ui-plp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Constructor-io","download_url":"https://codeload.github.com/Constructor-io/constructorio-ui-plp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Constructor-io%2Fconstructorio-ui-plp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31759540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["constructorio-integrations","javascript","react","react-hooks","typescript"],"created_at":"2025-03-09T20:06:12.081Z","updated_at":"2026-04-13T16:01:11.154Z","avatar_url":"https://github.com/Constructor-io.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Constructor PLP UI Library\n\n[![npm](https://img.shields.io/npm/v/@constructor-io/constructorio-ui-plp)](https://www.npmjs.com/package/@constructor-io/constructorio-ui-plp)\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Constructor-io/constructorio-ui-plp/blob/main/LICENSE)\n\n## Introduction\n\nA UI library that provides React components to manage the fetching and rendering logic for [Search](https://constructor.io/products/search/) \u0026 [Browse](https://constructor.io/products/browse/) product listing pages powered by Constructor. Typescript support is available.\n\nOur [Storybook Docs](https://constructor-io.github.io/constructorio-ui-plp/?path=/docs/general-introduction--documentation) are the best place to explore the behavior and the available configuration options for this UI library.\n\n## Installation\n\n```bash\nnpm i @constructor-io/constructorio-ui-plp\n```\n\n## Usage\n\n### Using the React Component\n\nThe `CioPlp` component handles state management, data fetching, and rendering logic for the entire PLP.\n\n```jsx\nimport CioPlp from '@constructor-io/constructorio-ui-plp';\n\nfunction YourComponent() {\n  return (\n    \u003cdiv\u003e\n      \u003cCioPlp apiKey='key_M57QS8SMPdLdLx4x' /\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n### Using the JavaScript Bundle\n\nThis is a framework agnostic method that can be used in any JavaScript project. The `CioPlp` function provides a simple interface to inject an entire PLP UI into the provided `selector`.\n\nIn addition to [PLP component props](https://constructor-io.github.io/constructorio-ui-plp/?path=/docs/components-cioplp--props), this function also accepts `selector` and `includeCSS`.\n\n```js\nimport CioPlp from '@constructor-io/constructorio-ui-plp/constructorio-ui-plp-bundled';\n\nCioPlp({\n  selector: '#plp-container',\n  includeCSS: true, // Include the default CSS styles - defaults to true\n  apiKey: 'key_M57QS8SMPdLdLx4x',\n  // ... additional arguments\n});\n```\n\n### 🛍️ Shopify-Specific Defaults\n\nWhen integrating with Shopify themes, you can use the `useShopifyDefaults` prop to enable Shopify-specific behavior:\n\n```jsx\n\u003cCioPlp apiKey='your-api-key' useShopifyDefaults={true} /\u003e\n```\n\n**What it provides:**\n\n- `callbacks.onAddToCart`: Adds products to the Shopify cart via `/cart/add.js` API\n- `callbacks.onProductCardClick`: Navigates to `/products/{itemId}`\n- `urlHelpers.setUrl`: Converts `/group_id/` URLs to `/collections/` for Shopify compatibility\n\n**For the JavaScript Bundle:**\n\nWhen using `useShopifyDefaults` with the bundled version, you can omit the `selector` parameter and it will default to `#cio-plp-ui-container`:\n\n```js\nCioPlp({\n  apiKey: 'your-api-key',\n  useShopifyDefaults: true,\n  // selector defaults to '#cio-plp-ui-container'\n});\n```\n\n**Note:** Any custom `callbacks` or `urlHelpers` you provide will override the Shopify defaults.\n\n## Custom Styling\n\n### Library Defaults\n\nBy default, importing React components from this library does not pull any CSS into your project.\n\nIf you wish to use starter styles from this library, add an import statement similar to the example import statement below:\n\n```js\nimport '@constructor-io/constructorio-ui-plp/styles.css';\n```\n\n- The starter styles can be used as a foundation to build on top of, or as a reference to be replaced completely.\n- To opt out of all default styling, simply do not import the `styles.css` stylesheet.\n- All starter styles in this library are scoped within the `.cio-plp` CSS selector.\n- The starter styles are intended to be extended by layering in your own CSS rules.\n- If the starter styles are imported, `CioPlp` component will take up the full width and height of the parent container.\n\n\u003e Please note the starter styles utilize @container queries and enable responsive styles for our PLPs based on the size of their container element. Since this feature is supported by modern browsers, polyfills have not been included in this library. However, if you want to support older browsers, you can add fallback styles or use a [polyfill](https://github.com/GoogleChromeLabs/container-query-polyfill).\n\n## Troubleshooting\n\n### Known Issues\n\n**Older JavaScript environments**\n\nThe library provides two different builds: CommonJS (cjs) and ECMAScript Modules (mjs).\n\nFor ECMAScript Modules (mjs) build. The JavaScript version is ESNext which might not be supported by your environment.\nIf that's the case and your environment is using an older JavaScript version like ES6 (ES2015), you may get this error:\n\n`Module parse failed: Unexpected token (15:32)\nYou may need an appropriate loader to handle this file type, currently no loaders are configured to process this file`\n\nTo solve this you can import the CommonJS (cjs) build which supports ES6 (ES2015) syntax:\n\n`import CioPlp from '@constructor-io/constructorio-ui-plp/cjs'`\n\n**ESLint**\n\nThere is a known issue with ESLint where it fails to resolve the paths exposed in the `exports` statement of NPM packages. If you are receiving the following error, you can safely disable ESLint using `// eslint-disable-line` for that line.\n\n`Unable to resolve path to module '@constructor-io/constructorio-ui-plp/styles.css'`\n\nRelevant open issues: [Issue 1868](https://github.com/import-js/eslint-plugin-import/issues/1868), [Issue 1810](https://github.com/import-js/eslint-plugin-import/issues/1810)\n\n## Local Development\n\n### Development Scripts\n\n```bash\nnpm ci                  # Install dependencies for local dev\nnpm run dev             # Start a local dev server for Storybook\nnpm run lint            # Run lint\n```\n\n### Library Maintenance\n\n```bash\nnpm run compile           # Generate lib folder for publishing to npm\nnpm run build-storybook   # Generate Storybook static bundle for deploy with GitHub Pages\n```\n\n## Publishing new versions\n\nDispatch the [Publish](https://github.com/Constructor-io/constructorio-ui-plp/actions/workflows/publish.yml) workflow in GitHub Actions. You're required to provide two arguments:\n\n- **Version Strategy**: `major`, `minor`, or `patch`.\n- **Title**: A title for the release.\n\nThis workflow will automatically:\n\n1. Bump the library version using the provided strategy.\n2. Create a new git tag.\n3. Create a new GitHub release.\n4. Compile the library.\n5. Publish the new version to NPM.\n6. Deploy the Storybook docs to GitHub Pages.\n7. Report the progress on the [relevant Slack channel](https://constructor.slack.com/archives/C061D3CFVR9).\n\n#### ℹ️ Note: Please don't manually increase the package.json version or create new git tags.\n\nThe library version is tracked by releases and git tags. We intentionally keep the package.json version at `0.0.0` to avoid pushing changes to the `main` branch. This solves many security concerns by avoiding the need for branch-protection rule exceptions.\n\n## New Storybook Version\n\nDispatch the [Deploy Storybook](https://github.com/Constructor-io/constructorio-ui-plp/actions/workflows/deploy-storybook.yml) workflow in GitHub Actions.\n\n#### ℹ️ Note: This is already done automatically when publishing a new version.\n\n## Supporting Docs\n\n- [Storybook 7 Introduction](https://storybook.js.org/docs/7.0/react/get-started/introduction)\n- [Typescript Docs](https://www.typescriptlang.org/docs/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructor-io%2Fconstructorio-ui-plp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconstructor-io%2Fconstructorio-ui-plp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructor-io%2Fconstructorio-ui-plp/lists"}