React SDK reference

This page lists what @shiprev/react exports, the props each export takes and the values it can show or return. For a walkthrough, start with The React components; for what to show your end users, see Show it in your frontend and Self-service.

Version

This page covers version 0.1.0-beta.0, the version published on npm, installed with the beta tag (npm install @shiprev/react@beta). It is a beta: the interface may change before 1.0. New versions are listed in the changelog.

React 19 is the only peer dependency, and the package has no runtime dependencies. The entry module starts with 'use client', so a Next.js App Router page can import it directly: the components render their loading state on the server and read data in the browser. The stylesheet is a separate import, @shiprev/react/styles.css, and is optional; see Styling.

The components display and collect input only. Whether an end user may use a capability is ruled in your backend by the Server SDK.

Exports

Data types keep the API's snake_case field names, because values pass between the API and your code unchanged.

Provider

ShipRevProvider supplies the network settings and the look to the components. Every component must be rendered inside a provider; outside one, rendering throws.

import { ShipRevProvider, UsageMeter } from '@shiprev/react';
import '@shiprev/react/styles.css';

export function App() {
  return (
    <ShipRevProvider apiBase="/shiprev" getAccessToken={getAccessToken} onUnauthorized={onUnauthorized} appearance={{ primaryColor: '#0f766e' }}>
      <UsageMeter />
    </ShipRevProvider>
  );
}

The provider and the components store nothing: no localStorage, sessionStorage or cookie, and no token kept in memory. Every request is sent with credentials: 'omit' and an x-request-id header of the form rsdk_<uuid>, and never to another origin.

ShipRevAppearance

Each field becomes a CSS variable or attribute on the provider's root element, which has the class sr-root.

Props every component takes

Each component below also takes these three props, listed again in its table:

• className: added to the component's root element, which always has the class sr-root.
• labels: any subset of the component's texts, replacing the English defaults; see Labels.
• onError: called with a ShipRevError once for each failed request, while the component shows its own error text. A missing session is not a failure: the component shows its signed-out state and does not call onError.

Sign-in form

SignInForm asks for email and password and sends POST /public/v1/auth/login. On success it calls onSignedIn once with the issued session, and keeps nothing.

An end user whose email address is not confirmed yet is refused with 403 EMAIL_VERIFICATION_REQUIRED: this version shows errorUnavailable, passes the error to onError, and does not ask for the code. Send such end users to the hosted pages; see Sign-in methods.

Sign-up form

SignUpForm asks for an organization name, email and password, and sends POST /public/v1/auth/register. On success it calls onSignedUp once with the issued session.

The region confirms a new email address before it issues a session, and this version cannot send an invitation, so a sign-up through SignUpForm does not complete: the region creates the account, emails a code and answers 403 EMAIL_VERIFICATION_REQUIRED, which the form shows as errorUnavailable without asking for the code, and onSignedUp is not called. Until a version with this step is published, send end users who sign up with a password to the hosted pages; see Sign-in methods. The texts verifyTitle and verifyBody are shown only when an issued session's account has email_verified set to false, which the region does not issue.

Pricing table

PricingTable lists the primary plans that have a published version, with the price of that version and one line per capability with its allowance; add-on plans are left out. The organization's current plan is marked.

What a choice does depends on the organization's subscription:

Before a switch, PricingTable asks only whether to switch, with confirmSwitchPrompt, which says that the change takes effect right away. It does not say that the difference is charged at once, and when the answer is PAYMENT_REQUIRED, the change takes effect only once the payment succeeds. To tell end users this, replace that text through the labels prop.

A refused checkout shows one of these texts:

A refused change shows one of these texts:

unverifiedEmail is shown for every other 403, including INSUFFICIENT_ROLE, which refuses members who are not an owner or admin of the organization (see Who may do what). To tell the two apart, read code in onError, or replace the text through labels.

Subscription panel

SubscriptionPanel shows the organization's plan, its status and the date its period renews, ends or ended, with a cancel action that asks for confirmation first.

The cancel action is shown when allowCancel is on, the subscription has not ended and no cancellation is scheduled. Confirming sends POST /public/v1/subscriptions/cancel; what that does to each kind of subscription is in Cancel and resume. A failed cancellation shows cancelError.

Before a cancellation, SubscriptionPanel shows confirmCancelPrompt, which says that the subscription stays active until the end of the period. That holds for a subscription paid through checkout; one without a card, or activated in the operator console, ends at once. If your end users can have such a subscription, replace that text through the labels prop.

Usage meter

UsageMeter reads GET /public/v1/usage/summary and shows, for each capability, the amount used in the current period out of the allowance, with a bar.

Amounts are shown as the decimal strings the API returns. The bar and usedOfAllowance are shown when the allowance is a number greater than 0; otherwise only usedOnly.

Labels

Every text a component shows is a key of its labels type. Pass any subset through the labels prop; keys you leave out keep the default. A {name} in a default is replaced by the component.

<SubscriptionPanel labels={{ cancel: 'End subscription', renewsOn: 'Next renewal: {date}' }} />

Sign-in form texts

Sign-up form texts

Pricing table texts

Subscription panel texts

{date} is the end of the current period, formatted in English and in UTC, for example Jan 31, 2027.

Usage meter texts

Data types

The fields are those of the Public API; times are ISO 8601 strings.

IssuedSession

AccountProfile

AccountMembership

PublicPlan

PublicPlanVersion

PublicEntitlementRule

Subscription

UsageSummary

UsageSummaryItem

Errors

Every failure passed to onError is a ShipRevError, which extends Error; its message is the message of the answer, or a generic one.

Styling

The stylesheet is optional. Without it, the components render unstyled, with class names that start with sr-. With it, every rule sits in the shiprev cascade layer, so any style of yours outside a layer wins. Change the look through appearance or these variables:

The package loads no fonts, images or icons.