@hellotrust/react

React SDK for displaying HelloTrust testimonials on your website.

Installation

npm install @hellotrust/react
# or
yarn add @hellotrust/react

Usage

Option 1: Using the Hook (Recommended)

import { useTestimonials } from '@hellotrust/react';

function TestimonialList() {
  const { testimonials, loading, error } = useTestimonials('your-showcase-id');

  if (loading) return <div>Loading testimonials...</div>;
  if (error) return <div>Error loading testimonials</div>;

  return (
    <div>
      {testimonials.map((testimonial) => (
        <div key={testimonial.id}>
          <p>{testimonial.final_text}</p>
          <p>- {testimonial.provider_name || testimonial.provider_email}</p>
        </div>
      ))}
    </div>
  );
}

Option 2: Using the Component with Render Prop

import { Testimonials } from '@hellotrust/react';

function TestimonialList() {
  return (
    <Testimonials showcaseId="your-showcase-id">
      {({ testimonials, loading, error }) => {
        if (loading) return <div>Loading testimonials...</div>;
        if (error) return <div>Error loading testimonials</div>;

        return (
          <div>
            {testimonials.map((testimonial) => (
              <div key={testimonial.id}>
                <p>{testimonial.final_text}</p>
                <p>- {testimonial.provider_name || testimonial.provider_email}</p>
              </div>
            ))}
          </div>
        );
      }}
    </Testimonials>
  );
}

TypeScript

The package includes full TypeScript type definitions:

import type { Testimonial, UseTestimonialsResult } from '@hellotrust/react';

interface Testimonial {
  id: string;
  final_text: string;
  provider_email: string;
  provider_name?: string;
  created_at: string;
}

interface UseTestimonialsResult {
  testimonials: Testimonial[];
  loading: boolean;
  error: Error | null;
}

Getting Your Showcase ID

1. Log in to your HelloTrust dashboard
2. Navigate to Settings → Showcases
3. Click on the showcase you want to display
4. Copy the showcase ID from the page

API

useTestimonials(showcaseId: string)

React hook that fetches testimonials from a showcase.

Parameters:

• showcaseId (string, required): The ID of the showcase to fetch testimonials from

Returns: UseTestimonialsResult

• testimonials (Testimonial[]): Array of testimonials in the showcase order
• loading (boolean): True while fetching testimonials
• error (Error | null): Error object if request failed, null otherwise

<Testimonials />

React component using the render prop pattern.

Props:

• showcaseId (string, required): The ID of the showcase to fetch testimonials from
• children (function, required): Render function that receives UseTestimonialsResult

Development vs Production

The SDK can be built in two modes:

Development (localhost):

yarn build:dev

Builds the SDK to connect to http://localhost:8080 for local development.

Production:

yarn build:prod

Builds the SDK to connect to https://api.hellotrust.io for production use.

The API URL is baked into the build at compile time for maximum reliability and performance.

License

MIT