Skip to content
BuildBase

Pre-built UI overview

Drop-in settings screens plus headless pricing and credit store components.

BuildBase ships with pre-built UI for the most common SaaS screens. One function call replaces months of UI work - fully translated, permission-gated, and responsive.

import { useSaaSAuth } from '@buildbase/sdk/react';

function SettingsButton() {
  const { openWorkspaceSettings } = useSaaSAuth();
  return <button onClick={() => openWorkspaceSettings()}>Settings</button>;
}

Settings screens

Call openWorkspaceSettings(section) to open any screen. Every screen opens in the same dialog, with the person's own screens under Account and the workspace's under Workspace, and the one you named already chosen. A screen that does not apply, such as billing before your app sells plans to people, is left out of the list.

The settings dialog opened with openWorkspaceSettings('users'): Account, Security, Devices and Connected agents under Account, Settings to Danger Zone under Workspace, and Members highlighted as step 1 beside the Workspace Members screen

SectionWhat it shows
profileUser name, email, username, language, country, currency, timezone
securityPassword, phone, two-step, connected accounts, passkeys, deletion
devicesSigned-in devices - rename, sign out, or forget a device
billingThe signed-in person's own plan, apart from any workspace: their plan, the plans on offer, and anything a workspace grants them. Shown once your app sells plans to people. See Users and workspaces
account-creditsThe signed-in person's own credit balance and history, apart from the workspace's credits. Shown beside billing when your app sells credit packs to people
connected-agentsConnected OAuth2 agents (e.g. MCP clients) - view and revoke access
my-sellingThe signed-in person as a seller: Start selling, Stripe's onboarding in the app, their status and payout account. Listed while selling is on
generalWorkspace name, icon, billing currency
usersInvite members by email, pending invitations, roles, seat usage
subscriptionCurrent plan, upgrade/downgrade, cancel/resume, invoices
usagePer-quota progress bars with consumption and overage
creditsCredit balance, transaction history
featuresToggle workspace feature flags
notificationsNotification preferences
permissionsRole permission configuration
enterpriseSingle sign-on for the company the workspace belongs to: the connection's status and the IT admin's setup, the directory and certificate cards, and for members who can edit settings the company's activity, access policy, insights and log streams, with WorkOS's export and audit log viewer when company audit logs are on (while enterprise sign-in is on; see settings screens)
sellingThe workspace as a seller, the same steps as my-selling. Listed while selling is on
dangerDelete workspace with confirmation

Every screen handles loading states, errors, permission checks, and translations automatically.

Two components appear on their own when they apply. <ImpersonationBanner /> is pinned to the bottom of the window while an app owner is signed in as the user, and <GuestUpgrade /> takes the place of the email and password parts of the profile and security screens for a guest. Both can also be placed in your own layout.

Page components

PricingPage

Headless pricing page: fetches plan data and handles checkout logic, you render the UI through a required render prop:

import { PricingPage } from '@buildbase/sdk/react';

function Pricing() {
  return (
    <PricingPage slug="main-pricing">
      {({ loading, error, plans, selectPlan }) => {
        if (loading) return <p>Loading plans...</p>;
        if (error) return <p>{error}</p>;

        return plans.map((plan) => (
          <button
            key={plan._id}
            onClick={() => selectPlan(plan._id, 'monthly', 'usd')}
          >
            Choose {plan.name}
          </button>
        ));
      }}
    </PricingPage>
  );
}

CreditStorePage

Headless credit store: fetches credit packages and handles purchase logic, you render the UI through a required render prop:

import { CreditStorePage } from '@buildbase/sdk/react';

function Credits() {
  return (
    <CreditStorePage>
      {({ loading, error, packages, selectPackage }) => {
        if (loading) return <p>Loading packages...</p>;
        if (error) return <p>{error}</p>;

        return packages.map((pkg) => (
          <button key={pkg._id} onClick={() => selectPackage(pkg._id)}>
            Buy {pkg.creditAmount} credits - {pkg.name}
          </button>
        ));
      }}
    </CreditStorePage>
  );
}

BetaForm

Beta signup form:

import { BetaForm } from '@buildbase/sdk/react';

function BetaPage() {
  return <BetaForm onSuccess={() => alert('You are on the list!')} />;
}

Connected agents

<ConnectedAgents /> lists the AI agents (OAuth2 clients, such as MCP clients) the signed-in user has authorized to access their account, with a per-row Disconnect action. It is the same screen openWorkspaceSettings('connected-agents') opens - render it directly to embed it in your own page. It is a drop-in component; all props are optional:

import { ConnectedAgents } from '@buildbase/sdk/react';

function AgentsPage() {
  return <ConnectedAgents />;
}

Set the mcp prop on SaaSOSProvider to add a Connect an agent guide to the screen - a copyable server URL, a paste-to-connect prompt for chat assistants, and setup snippets for the major AI apps (ChatGPT, Claude, Cursor, VS Code, Windsurf, Cline by default; override via mcp.clients):

import { SaaSOSProvider } from '@buildbase/sdk/react';

<SaaSOSProvider
  mcp={{
    url: 'https://app.example.com/api/mcp',
    name: 'Acme',
    docsUrl: 'https://docs.example.com/agents',
  }}
>

The guide is also exported standalone as <ConnectMcpGuide /> - render it anywhere (an onboarding step, a docs page). It reads the provider's mcp config by default, accepts an explicit config prop, and renders null when no MCP url is configured.

For a fully custom UI, useConnectedAgents() returns headless data and actions, session-authed and scoped to the signed-in user:

FieldTypeDescription
agentsIConnectedAgent[]Connected agents - clientId, title, granted scope, lastGrantedAt
loadingbooleantrue while the initial list is loading
errorstring | nullError message from the last list or revoke, if any
revokingstring | nullThe clientId currently being disconnected, or null
refresh() => Promise<void>Re-fetches the list
revoke(clientId) => Promise<void>Disconnects an agent, then optimistically drops it from the list

An agent the person's company approved through its identity provider, with no consent screen (agents through a company's identity provider), is in the same list. The server marks it with source: "idp" (consent when the person approved it themselves); SDK 1.0.0 carries source on IConnectedAgent and says so on the screen. Disconnecting it ends its live access, but the company's identity provider may approve it again.

Inline openers

Open billing or credit UI from anywhere - buttons, banners, feature gates:

import { useSaaSAuth } from '@buildbase/sdk/react';

function UpgradePrompt() {
  const { openPlanPicker, openCreditStore } = useSaaSAuth();

  return (
    <div>
      <button onClick={() => openPlanPicker()}>Upgrade Plan</button>
      <button onClick={() => openCreditStore()}>Buy Credits</button>
    </div>
  );
}
MethodOpens
openWorkspaceSettings(section?)Full settings dialog
openPlanPicker()Plan selection UI
openCreditStore()Credit purchase UI

The Built with BuildBase badge

Show a small "Built with BuildBase" badge in your footer, with your referral code if you have one. <BuildBaseBadge /> renders it in three variants and four themes. It needs no provider and makes no network call of its own, so it fits a footer outside SaaSOSProvider. Props and the plain HTML version: Badge.

import { BuildBaseBadge } from '@buildbase/sdk/react';

function Footer() {
  return <BuildBaseBadge variant="powered-by" theme="auto" />;
}

Built-in capabilities

All pre-built UI includes:

  • Permission gating - actions hidden based on user's role
  • 8 languages - translated via the locale prop on SaaSOSProvider
  • Responsive - adapts to mobile, tablet, and desktop
  • Loading and error states - skeleton loaders, inline errors, retry buttons

Next Steps