React SDK
React hooks and components for integrating Quotient into React applications
Installation
npm install @quotientjs/react
QuotientProvider
Context provider that gives child components the Quotient client. Create the
client once with QuotientClient.init() in a file of its own, then pass it to
the provider. Creating it at the top of a module is safe even in apps that
render on the server: the client does nothing until it's used in the browser.
// lib/quotient.ts
import { QuotientClient } from "@quotientjs/react";
export const quotient = QuotientClient.init({
apiKey: "pk_your_public_api_key",
});
import { QuotientProvider } from "@quotientjs/react";
import { quotient } from "./lib/quotient";
function App() {
return <QuotientProvider client={quotient}>{children}</QuotientProvider>;
}
| Prop | Type | Required | Description |
|---|---|---|---|
client | QuotientClient | Yes | The client created with QuotientClient.init() |
Use the client in effects and event handlers, not while a component renders. On the server the client exists but can't do anything, so calling it during a server render throws.
Page views
The client tracks page views when it starts and on every navigation. Choose
which pages are tracked with the pageViews option of QuotientClient.init():
export const quotient = QuotientClient.init({
apiKey: "pk_your_public_api_key",
// Track every page except the logged-in app
pageViews: (url) => !url.pathname.startsWith("/app"),
});
Set pageViews: false if another integration already sends Quotient page views
from the same app.
Passing client options (deprecated)
clientOptions and autoTrackPageViews are deprecated. Create the client with
QuotientClient.init() and pass it as client instead.
useQuotient
Access the Quotient client and context within React components.
import { useQuotient } from "@quotientjs/react";
function MyComponent() {
const {
client, // The QuotientClient passed to the provider
error, // Error or null if initialization failed
reset, // () => void: Clear storage and start fresh
} = useQuotient();
}
| Field | Type | Description |
|---|---|---|
client | QuotientClient | null | The client passed to the provider. null only with the deprecated clientOptions, until the client is created |
error | Error | null | Set if initialization failed |
reset | () => void | Clear all stored data and give the browser a new device ID |
useBlogs
Fetch a paginated list of blogs within a client component. Must be inside a <QuotientProvider>.
| Param | Type | Required | Description |
|---|---|---|---|
page | number | No | Page number |
limit | number | No | Results per page |
statuses | BlogStatus[] | No | Filter by status |
"use client";
import { BlogStatus, useBlogs } from "@quotientjs/react";
export default function BlogList({
page,
limit,
statuses,
}: {
page: number;
limit: number;
statuses: BlogStatus[];
}) {
const { data, isLoading } = useBlogs({
page,
limit,
statuses,
});
const { blogs, pageData } = data;
return (
{/* Render blog list */}
);
}
Common Patterns
User Identification on Login
"use client";
import { useQuotient } from "@quotientjs/react";
function LoginHandler() {
const { client } = useQuotient();
const handleLogin = async (user) => {
await client?.audience.people.identify({
emailAddress: user.email,
firstName: user.firstName,
lastName: user.lastName,
lists: ["customers"],
});
};
return <button onClick={() => handleLogin(user)}>Login</button>;
}
Newsletter Signup
From the browser, a signup goes through subscribeToEmail(), which follows
your double opt-in setting. People unsubscribe from the link in their own
emails, so a website can't unsubscribe anyone.
"use client";
import { useQuotient } from "@quotientjs/react";
import { useState } from "react";
function NewsletterSignup() {
const [email, setEmail] = useState("");
const { client } = useQuotient();
const signUp = async () => {
// The client isn't ready yet
if (!client) {
return;
}
try {
await client.audience.people.subscribeToEmail({
emailAddress: email,
lists: ["newsletter"],
});
toast.success("Thanks for signing up");
} catch (error) {
toast.error("Couldn't sign you up");
}
};
return (
<div>
<input value={email} onChange={(e) => setEmail(e.target.value)} />
<button onClick={signUp} disabled={!client}>
Sign up
</button>
</div>
);
}