1. Overview
The ParityDeals React UI SDK provides a complete React-based solution for integrating dynamic, customizable pricing tables and paywalls into web applications. It handles fetching offering data, displaying pricing plans with multiple billing periods, managing subscriptions, and processing checkouts with full localization support.2. Installation
Install the SDK using npm or yarn:3. Quick Start
Basic Setup
Note: You must import the CSS file for the components to be styled correctly.With Custom Event Handling
4. Core Components
4.1. ParityDealsProvider
The top-level provider component that initializes the SDK and manages the global state.
Required Props
Prop | Type | Description |
---|---|---|
accessToken | string | Your ParityDeals client access token |
offeringId | string | The unique identifier for your offering |
Optional Props
Prop | Type | Default | Description |
---|---|---|---|
customerId | string | undefined | Customer identifier for personalized pricing |
environment | sandbox|production | ’production’ | The environment to use. If you want to use the sandbox, you must provide this. |
checkoutSuccessUrl | string | window.location.href | URL to redirect after successful checkout |
apiConfig | ParityDealsAPIConfig | {} | Advanced API configuration options |
API Configuration Options
4.2. PDPricingTable
The main pricing table component that displays all plans and handles user interactions.
Props
Prop | Type | Default | Description |
---|---|---|---|
customStyles | PricingTableStyle | {} | Custom styling configuration |
customActionButton | CustomActionButton | undefined | Custom button component |
customCheckIcon | React.ReactNode | undefined | Custom check icon |
customUnCheckIcon | React.ReactNode | undefined | Custom uncheck icon |
customTooltipIcon | React.ReactNode | undefined | Custom tooltip icon |
onCustomPriceClick | (details: PlanClickDetails) => void | undefined | Callback for custom price plans |
renderActionButtonAfter | features | price | price | Render the action button after the features or the price |
insertElements.* | InsertElements | {} | Insert custom elements anywhere in the pricing table |
insertElements.beforePlanName | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements before the plan name |
insertElements.afterPlanName | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements after the plan name |
insertElements.beforePlanDescription | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements before the plan description |
insertElements.afterPlanDescription | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements after the plan description |
insertElements.beforePrice | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements before the price |
insertElements.afterPrice | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements after the price |
insertElements.beforeFeatures | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements before the features |
insertElements.afterFeatures | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements after the features |
insertElements.beforeActionButton | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements before the action button |
insertElements.afterActionButton | (plan: OfferingPlan, activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements after the action button |
insertElements.beforeSwitch | (activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements before the switch |
insertElements.afterSwitch | (activePeriod: ChargePeriodEnum) => JSX.Element | undefined | Insert custom elements after the switch |
Example Usage
4.3. PDPlan
Renders a list of pricing plans with billing period switching.
Props
Prop | Type | Required | Description |
---|---|---|---|
plans | OfferingPlan[] | Yes | Array of plans to display |
pricingTable | PricingTable | Yes | Pricing table configuration |
billingPeriods | BillingPeriod[] | Yes | Available billing periods |
countryCode | string | Yes | Country code for localization |
currencyCode | string | Yes | Currency code (e.g., “USD”) |
currencySymbol | string | Yes | Currency symbol (e.g., ”$“) |
currencyConversionRate | number | Yes | Currency conversion rate |
pricingLocale | string | Yes | Locale for price formatting |
onPlanClick | (details: PlanClickDetails) => void | Yes | Plan selection callback |
customStyles | PricingTableStyle | No | Custom styling |
customActionButton | CustomActionButton | No | Custom button component |
actionButtonLoadingPlanIdentifier | string | No | Loading state for specific plan |
noStyles | boolean | No | Disable default styling |
4.4. PDPlanItem
Displays a single pricing plan card.
Props
Prop | Type | Required | Description |
---|---|---|---|
plan | OfferingPlan | Yes | Plan data to display |
pricingTable | PricingTable | Yes | Pricing table configuration |
period | ChargePeriodEnum | Yes | Current billing period |
countryCode | string | Yes | Country code |
currencyCode | string | Yes | Currency code |
currencySymbol | string | Yes | Currency symbol |
currencyConversionRate | number | Yes | Conversion rate |
pricingLocale | string | Yes | Locale for formatting |
onPdPlanItemClick | (details: PlanClickDetails) => void | Yes | Click handler |
customActionButton | CustomActionButton | No | Custom button |
actionButtonText | string | No | Button text |
actionButtonLoading | boolean | No | Loading state |
actionButtonDisabled | boolean | No | Disabled state |
isActive | boolean | No | Active plan indicator |
successText | string | No | Success message |
noStyles | boolean | No | Disable styling |
4.5. PDPrice
Renders formatted price display with currency and period information.
Props
Prop | Type | Required | Description |
---|---|---|---|
price | number | Yes | Price amount |
countryCode | string | Yes | Country code |
currencyCode | string | Yes | Currency code |
currencySymbol | string | Yes | Currency symbol |
currencyConversionRate | number | Yes | Conversion rate |
pricingLocale | string | Yes | Locale for formatting |
period | ChargePeriodEnum | Yes | Billing period |
showDecimal | boolean | Yes | Show decimal places |
showCurrencySymbol | boolean | Yes | Show currency symbol |
showCurrencyCode | boolean | Yes | Show currency code |
minimumFractionDigits | number | Yes | Minimum decimal places |
maximumFractionDigits | number | Yes | Maximum decimal places |
4.6. PDFeatures
Renders the features list for a plan.
Props
Prop | Type | Required | Description |
---|---|---|---|
features | OfferingFeature[] | Yes | Array of features |
period | ChargePeriodEnum | Yes | Current billing period |
customCheckIcon | React.ReactNode | No | Custom check icon |
customUnCheckIcon | React.ReactNode | No | Custom uncheck icon |
customTooltipIcon | React.ReactNode | No | Custom tooltip icon |
descriptionTooltipEnabled | boolean | No | Enable tooltips |
onUsageChange | (featureId: string, quantity: number) => void | No | Usage change handler |
5. Data Types
Core Types
Color Configuration
Typography Configuration
Layout Configuration
6. Styling and Customization
6.1. CSS Variables
The SDK uses CSS variables for styling. You can override these in your CSS:6.2. Custom Styles Object
6.3. Custom Action Button
6.4. noStyles Mode
For complete styling control, use thenoStyles
prop:
6.5. CSS Class Reference
The ParityDeals React UI components use consistent CSS class names that you can target for custom styling. All classes are prefixed withpd-
to avoid naming conflicts.
CSS Class Hierarchy
7. Advanced Features
7.1. Usage-Based Pricing
The SDK supports metered billing and tiered pricing:7.2. Custom Price Plans
Handle custom pricing plans with theonCustomPriceClick
callback:
7.3. Subscription Management
The SDK automatically handles subscription updates:- New Subscriptions: Redirects to checkout
- Plan Upgrades/Downgrades: Updates existing subscription
- Free Plan Upgrades: Handles free trial to paid conversion
7.4. Error Handling
8. Complete Example
9. API Endpoints
The SDK uses the following default API endpoints:- Offering API:
https://api.paritydeals.com/api/v1/monetization/public-offering
- Checkout API:
https://api.paritydeals.com/api/v1/checkout/
- Subscription API:
https://api.paritydeals.com/api/v1/subscriptions
apiConfig
:
10. Troubleshooting
Common Issues
- Loading State: Ensure your
accessToken
andofferingId
are correct - Styling Issues: Check CSS variable overrides and custom styles
- API Errors: Verify API endpoints and network connectivity
- TypeScript Errors: Ensure all required props are provided
Debug Mode
Enable console logging for debugging:Using the Sandbox
If you want to use the sandbox, you need to set theenvironment
option to sandbox
in the ParityDealsProvider
.
12. Support
For technical support and questions:- Documentation: docs.paritydeals.com
- GitHub Issues: github.com/paritydeals/react-ui
- Email: support@paritydeals.com