@simplersuite/reviews-components

Headless React components for SimplerSuite Reviews — ratings and reviews for Shopify storefronts.

• Headless by default — semantic HTML with data-sr-* attributes you can target with CSS
• Optional default styles — polished defaults using :where() for zero specificity (your CSS always wins)
• Stars or thumbs — all components automatically adapt to your shop's rating type
• React 18 & 19 compatible

Install

npm install @simplersuite/reviews-components

Quick Start

Wrap your app in <SimplerSuiteReviewsProvider>, then drop in any components:

import {
  SimplerSuiteReviewsProvider,
  ReviewBadge,
  ReviewSummary,
  ReviewList,
  ReviewCarousel,
  ReviewForm,
} from '@simplersuite/reviews-components';

// Optional — polished default styles (zero specificity, your CSS always wins)
import '@simplersuite/reviews-components/styles.css';

function ProductPage({ product }) {
  return (
    <SimplerSuiteReviewsProvider
      apiKey="sr_your_api_key"
      shopDomain="your-store.myshopify.com"
    >
      <ReviewBadge productId={product.id} />
      <h1>{product.title}</h1>
      <ReviewSummary productId={product.id} />
      <ReviewCarousel productId={product.id} visibleCount={3} />
      <ReviewList productId={product.id} perPage={10} />
      <ReviewForm productId={product.id} />
    </SimplerSuiteReviewsProvider>
  );
}

Components

| Component | Description | |---|---| | ReviewSummary | Aggregate rating with distribution bars | | ReviewList | Paginated review list with "Load More" | | ReviewCarousel | Horizontal carousel with arrows, dots, swipe, keyboard nav | | ReviewBadge | Compact inline rating badge for product listings | | ReviewForm | Review submission form (stars or thumbs) | | ReviewFilters | Sort and rating filter controls | | ReviewPhotos | Photo grid with lightbox | | ReviewStars | Pure star display (no data fetching) | | ReviewThumbs | Pure thumbs up/down display | | ReviewRating | Auto-selects stars or thumbs based on rating type |

Hooks

Build fully custom UIs with the included hooks:

import { useReviews, useReviewSummary, useSubmitReview } from '@simplersuite/reviews-components';

• useReviews(productId, options?) — paginated reviews with sort/filter
• useReviewSummary(productId) — aggregate rating data
• useSubmitReview(productId) — submit a new review

Styling

Import the default stylesheet or style from scratch using data-sr-* attributes:

// Option 1: Default styles (zero specificity)
import '@simplersuite/reviews-components/styles.css';

// Option 2: Override CSS custom properties
:root {
  --sr-primary: #8b5cf6;
  --sr-star: #ec4899;
  --sr-radius: 8px;
  --sr-thumb-up: #16a34a;
  --sr-thumb-down: #dc2626;
}

// Option 3: Target data attributes directly
[data-sr-review] { /* your styles */ }

Documentation

Full documentation with prop tables, styling guides, and framework-specific guides (Next.js, Hydrogen) at docs.simplersuite.co.

License

UNLICENSED