Hooks

All hooks must be used inside a <SimplerSuiteReviewsProvider>. They return a ratingType field so your UI can adapt to the shop’s rating configuration (stars or thumbs).

useReviews

Fetch and paginate reviews for a product. Handles loading, error, sort, and pagination state. Reviews accumulate as the user loads more pages.

import { useReviews } from '@simplersuite/react';

function MyReviews({ productId }) {
  const {
    reviews,
    loading,
    error,
    hasMore,
    loadMore,
    sort,
    setSort,
    ratingType,
  } = useReviews(productId, {
    perPage: 10,
    sort: 'newest',
  });

  if (loading && reviews.length === 0) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <select value={sort} onChange={(e) => setSort(e.target.value)}>
        <option value="newest">Newest</option>
        <option value="highest">Highest</option>
        <option value="lowest">Lowest</option>
      </select>

      {reviews.map((review) => (
        <div key={review.id}>
          <strong>{review.author.name}</strong> — {review.rating}
          <p>{review.body}</p>
        </div>
      ))}

      {hasMore && <button onClick={loadMore}>Load More</button>}
    </div>
  );
}

Options

Option	Type	Default	Description
`perPage`	`number`	`10`	Reviews per page
`sort`	`ReviewSortOption`	`"newest"`	Initial sort order
`rating`	`number`	—	Filter by star rating (1-5). Omit to show all.
`enabled`	`boolean`	`true`	Set to `false` to disable auto-fetching. Useful for conditional loading.

Return Value

Property	Type	Description
`reviews`	`Review[]`	Accumulated reviews across loaded pages
`loading`	`boolean`	`true` while fetching. Starts as `true` on mount (when enabled).
`error`	`ApiError \| null`	Error object with `status`, `message`, and optional `code`
`page`	`number`	Current page number
`hasMore`	`boolean`	Whether more pages are available
`loadMore`	`() => void`	Fetch the next page (appends to existing reviews)
`sort`	`ReviewSortOption`	Current sort order
`setSort`	`(sort: ReviewSortOption) => void`	Change sort order (resets to page 1 and replaces reviews)
`ratingType`	`"stars"` \| `"thumbs"`	The shop’s rating type, extracted from the API response

useReviewSummary

Fetch aggregate rating data for a product — average rating, total count, and rating distribution.

import { useReviewSummary } from '@simplersuite/react';

function MySummary({ productId }) {
  const { summary, loading, error, ratingType } = useReviewSummary(productId);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!summary) return null;

  return (
    <div>
      <p>{summary.averageRating} average from {summary.totalReviews} reviews</p>
      <p>Rating type: {ratingType}</p>
    </div>
  );
}

Return Value

Property	Type	Description
`summary`	`ReviewSummary \| null`	Summary data after loading. Contains `averageRating`, `totalReviews`, `distribution`, and `ratingType`.
`loading`	`boolean`	`true` while fetching
`error`	`ApiError \| null`	Error object
`ratingType`	`"stars"` \| `"thumbs"`	Convenience field extracted from the summary (defaults to `"stars"` while loading)

useSubmitReview

Submit a review programmatically. Use this when building a fully custom review form instead of <ReviewForm>.

import { useSubmitReview } from '@simplersuite/react';

function MyForm({ productId }) {
  const { submit, loading, error, success, reset } = useSubmitReview();

  async function handleSubmit(e) {
    e.preventDefault();
    await submit({
      productId,
      rating: 5,          // 1-5 for stars, 0 or 1 for thumbs
      title: 'Great!',
      body: 'Loved it.',
      author: {
        name: 'Jane',
        email: 'jane@example.com',
      },
    });
  }

  if (success) return <p>Thanks for your review! <button onClick={reset}>Write another</button></p>;

  return (
    <form onSubmit={handleSubmit}>
      {error && <p>Error: {error.message}</p>}
      {/* ... form fields ... */}
      <button type="submit" disabled={loading}>
        {loading ? 'Submitting...' : 'Submit'}
      </button>
    </form>
  );
}

Return Value

Property	Type	Description
`submit`	`(data: SubmitReviewData) => Promise<Review \| null>`	Submit function. Returns the created review on success, `null` on error.
`loading`	`boolean`	`true` while submitting
`error`	`ApiError \| null`	Error object
`success`	`boolean`	`true` after a successful submission
`reset`	`() => void`	Reset `success` and `error` state (e.g. to show the form again)