Constructor Recommendations UI

A UI library that provides React components to manage the fetching and rendering logic for Recommendations powered by Constructor.

Documentation

View the full component documentation and live examples in Storybook:

Explore Storybook Documentation →

Table of Contents

• Overview
• Installation & Quick Start
• Integration Modes
• Customization
• Troubleshooting
• Resources
• Contributing
• License

Overview

Constructor Recommendations UI provides React components for rendering personalized product recommendations. It handles state management, data fetching, and rendering logic out of the box.

Key capabilities:

• 🔌 Plug & Play – Ready-to-use React components for recommendations
• ⚡ Automatic Data Fetching – Built-in state management and data fetching
• 🎨 Customizable Styling – Minimal default styles, easy to extend or replace
• 🌐 Framework Agnostic – Use with React or as a vanilla JavaScript bundle
• 🛡 TypeScript Support – Full type safety included out of the box

Explore full documentation →

Installation & Quick Start

Install via npm

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

Basic Usage (React)

import CioRecommendations from '@constructor-io/constructorio-ui-recommendations';
import '@constructor-io/constructorio-ui-recommendations/styles.css';

function App() {
  return <CioRecommendations apiKey='key_M57QS8SMPdLdLx4x' />;
}

View detailed setup guide →

Integration Modes

React Component

import CioRecommendations from '@constructor-io/constructorio-ui-recommendations';

function YourComponent() {
  return <CioRecommendations apiKey='key_M57QS8SMPdLdLx4x' />;
}

Vanilla JavaScript (Bundle)

This is a framework agnostic method that can be used in any JavaScript project. The CioRecommendations function provides a simple interface to inject an entire recommendations UI into the provided selector.

In addition to recommendation component props, this function also accepts selector and includeCSS.

import CioRecommendations from '@constructor-io/constructorio-ui-recommendations/constructorio-ui-recommendations-bundled';

CioRecommendations({
  selector: '#recommendations-container',
  includeCSS: true,
  apiKey: 'key_M57QS8SMPdLdLx4x',
});

Customization

By default, importing React components from this library does not pull any CSS into your project.

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

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

• The starter styles can be used as a foundation to build on top of, or as a reference to be replaced completely.
• To opt out of all default styling, simply do not import the styles.css stylesheet.
• All starter styles in this library are scoped within the .cio-recommendations CSS selector.
• The starter styles are intended to be extended by layering in your own CSS rules.
• If the starter styles are imported, CioRecommendations component will take up the full width and height of the parent container.

Troubleshooting

| Issue | Solution | | ------------------- | ---------------------------------------------------------------------------------- | | Module not found | Run npm install @constructor-io/constructorio-ui-recommendations | | Need CommonJS build | Import CommonJS: require('@constructor-io/constructorio-ui-recommendations/cjs') |

Need more help? Open a GitHub issue

Resources

• Storybook Documentation - Interactive API reference and examples
• Constructor.io JS Client - Core API client
• Constructor.io Docs - Platform documentation

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 test && npm run lint locally.
4. Submit a PR for review.

License

MIT License

Copyright (c) 2022-present Constructor.io Corporation