PayBox Connect for React

Drop Claude and ChatGPT setup into your website. Separate buttons or a combined rolling logo/name button open instructions and video walkthroughs in place. Fonts inherit from your website; colors, shapes, spacing, copy, and videos are customizable.

Install

npm install @paybox-sh/connect-react

Requires React 18.2 or 19, a React web application, and a modern browser with native dialog support. No Tailwind, Next.js, animation library, or provider wrapper required. The component never authenticates, requests wallet permissions, or reports a successful connection; users complete authorization in their selected AI app.

Drop it in

import { ConnectButton } from '@paybox-sh/connect-react';
import '@paybox-sh/connect-react/styles.css';

export function Connect() {
  return <ConnectButton partnerSlug="your-partner-slug" />;
}

partnerSlug must be your enabled PayBox partner slug. It produces https://api.paybox.sh/mcp?app=your-partner-slug. app.paybox.sh hosts the account UI and does not serve the MCP endpoint. Use mcpUrl for an alternative MCP deployment; the component adds/replaces its app query parameter. A slug is routing, not authorization.

The default combined button rolls between Claude and ChatGPT and opens a chooser. The visual rotation pauses on hover/focus and stops for reduced-motion preferences. The accessible label stays “Connect with Claude or ChatGPT.”

Separate buttons

<ConnectButton partnerSlug="your-partner-slug" provider="claude" />
<ConnectButton partnerSlug="your-partner-slug" provider="chatgpt" />

Match your brand

<ConnectButton
  partnerSlug="your-partner-slug"
  partnerName="Your Partner Name"
  theme={{
    fontFamily: 'inherit',
    fontSize: '16px',
    background: '#c7f284',
    color: '#17221b',
    borderColor: '#425744',
    radius: '999px',
    padding: '14px 24px',
    panelBackground: '#faf9f9',
    panelColor: '#141414',
    panelRadius: '16px',
    accent: '#63852e',
  }}
/>

partnerName is the display name. The heading reads “Enable Your Partner Name with PayBox” when it is Your Partner Name; omitting it uses the partner slug in that heading. It also sets the instruction copy and Claude connector prefill (defaulting to PayBox). Videos remain the existing PayBox walkthroughs. Logos use the current text color. No fonts or logo images are fetched externally.

For CSS-first styling, use className or style on the wrapper and variables such as --pbx-connect-background, --pbx-connect-font-family, and --pbx-connect-panel-radius. Every theme property maps to its kebab-case variable. Load overrides after the package stylesheet. classNames targets button, dialog, providers, video, steps, url, settings, and close.

All theme controls

Values are CSS strings, including units where needed (18px, 1rem, 100%). lineHeight uses a unitless number string such as 1.5. Use none for shadows, 0px for border or outline width, and standard CSS shorthand for padding/margin. All settings are optional; omitted values preserve the defaults.

| Area | Theme properties | | --- | --- | | Typography | fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, textTransform | | Logos and layout | iconSize, gap, width, minHeight, padding, margin, radius | | Border | borderColor, borderWidth, borderStyle | | Decorative outline | outlineColor, outlineWidth, outlineStyle, outlineOffset | | Colors and effects | background, color, hoverBackground, hoverColor, shadow | | Animation | transitionDuration, transitionEasing, hoverLift, hoverScale, hoverShadow, pressScale, rotationDuration | | Keyboard focus | accent, focusOutlineWidth, focusOutlineOffset | | Dialog | panelBackground, panelColor, panelFontSize, panelWidth, panelPadding, panelRadius, panelBorderColor, panelBorderWidth, panelShadow, controlRadius |

margin applies outside the entire component; padding applies inside the trigger. Border and decorative outline are independent. Keyboard focus has its own outline, which replaces the decorative outline while focused; keep it visible for keyboard users. Dialog width is capped to fit the viewport. Hover colors inherit the normal button colors unless overridden. panelFontSize can keep instructions readable when the button uses a smaller font. The playground exposes every theme property.

<ConnectButton
  partnerSlug="your-partner-slug"
  partnerName="Your Partner Name"
  theme={{
    fontSize: '18px',
    fontWeight: '600',
    margin: '12px 0',
    padding: '16px 28px',
    borderWidth: '2px',
    borderStyle: 'solid',
    outlineWidth: '3px',
    outlineColor: '#c7f284',
    outlineOffset: '4px',
    panelFontSize: '16px',
  }}
/>

Light animation

Hover colors, border colors, shadow, and transforms transition together. By default, transitions take 180ms with ease-out, hover lifts the button 2px, and pressing scales it to 0.98. Lift/hover scale apply only on devices that support hover. The logo cycle duration covers both providers; each gets half the cycle.

<ConnectButton
  partnerSlug="your-partner-slug"
  partnerName="Your Partner Name"
  theme={{
    transitionDuration: '240ms',
    transitionEasing: 'ease-in-out',
    hoverLift: '3px',
    hoverScale: '1.02',
    hoverShadow: '0 8px 20px #00000020',
    pressScale: '0.98',
    rotationDuration: '8s',
  }}
/>

Use CSS time values (ms or s), unitless scale values, and a positive logo cycle duration. Set hoverLift: '0px', hoverScale: '1', and pressScale: '1' for no movement, or transitionDuration: '0ms' for immediate state changes. A custom CSS cubic-bezier(...) easing is supported. Reduced-motion preferences disable all transitions, lift/scale effects, and logo rotation; hover colors still change.

Copy and video overrides

<ConnectButton
  partnerSlug="your-partner-slug"
  label="Use Your Partner Name with AI"
  guides={{
    claude: {
      video: 'https://example.com/claude-setup.mp4',
      connectStep: 'Connect your account to get started.',
    },
  }}
/>

label replaces the entire trigger content, including the rolling logos. Pass an aria-label if the replacement has no readable text. guides accepts per-provider settingsStep, createStep, connectStep, and video. showVideo={false} hides videos. Standard anchor props, including click handlers and analytics data attributes, pass to the trigger; onClick can call preventDefault() to take over.

Videos autoplay muted when setup opens or the selected provider changes. Set autoPlayVideo={false} to require pressing Play instead. Playback stops when the dialog closes. Browsers that block autoplay still show native playback controls. Videos stream from https://paybox.sh/videos/ only after opening setup; they are not bundled into your JavaScript. If your site uses CSP, allow https://paybox.sh in media-src, or supply self-hosted video URLs. These are the same PayBox-branded walkthroughs used on the landing page. A failed video leaves all text instructions available; failed clipboard access leaves a selectable URL.

Server rendering and Next.js

The package preserves "use client". Import the CSS in your root layout in Next.js and use ConnectButton from either a server or client component. Callback props require a client component. The server-rendered trigger has a real settings URL: Claude carries a prefilled partner connector; ChatGPT opens settings. The full in-page guide requires JavaScript. Modified clicks retain normal link behavior.

Local development and release

pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm typecheck:example
pnpm test:landing
pnpm dev
npm pack

The playground runs at http://127.0.0.1:3210. npm pack builds a self-contained tarball with ESM, TypeScript declarations, and CSS. Install that tarball into a partner app before publishing. Build tools are development-only dependencies; React and React DOM are compatible-range peers so the host supplies one copy.

The landing page consumes src/content.ts as the canonical Claude/ChatGPT copy. Update it when changing the guides. The React SVG paths come from the existing landing-page model marks. Media remains hosted with the landing-page assets.

npm release setup

The connect-react.yml workflow checks builds, tests, the playground types, landing copy, and package contents on PRs. connect-react-release.yml repeats validation and publishes an unpublished version only from main. Merging to develop does not publish. An existing version is skipped; registry errors fail the release.

Installation, builds, tests, version checks, and packing run in a job without OIDC permission. A separate publish job on a fresh runner receives only that run's package tarball by artifact ID. It does not check out source, install project dependencies, or run package scripts; only this job has id-token: write. Publishing uses --ignore-scripts so lifecycle hooks cannot rebuild or execute package code with publishing access. This isolates credentials; it does not prove that a compromised build produced safe package contents.

Before the first release, a maintainer with access to the @paybox-sh npm scope must publish the initial package from the reviewed release checkout using npm publish --access public, then configure its npm trusted publisher:

• Organization: moonpay
• Repository: paybox
• Workflow filename: connect-react-release.yml
• Allow direct npm publish for this publisher.

Future releases bump package.json's version and promote the reviewed change to main. The workflow uses GitHub OIDC without a stored npm token. See the npm trusted publishing documentation. No package is published by local build, test, or pack commands.