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.

| Section | What it shows |
|---|---|
profile | User name, email, username, language, country, currency, timezone |
security | Password, phone, two-step, connected accounts, passkeys, deletion |
devices | Signed-in devices - rename, sign out, or forget a device |
billing | The 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-credits | The 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-agents | Connected OAuth2 agents (e.g. MCP clients) - view and revoke access |
my-selling | The signed-in person as a seller: Start selling, Stripe's onboarding in the app, their status and payout account. Listed while selling is on |
general | Workspace name, icon, billing currency |
users | Invite members by email, pending invitations, roles, seat usage |
subscription | Current plan, upgrade/downgrade, cancel/resume, invoices |
usage | Per-quota progress bars with consumption and overage |
credits | Credit balance, transaction history |
features | Toggle workspace feature flags |
notifications | Notification preferences |
permissions | Role permission configuration |
enterprise | Single 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) |
selling | The workspace as a seller, the same steps as my-selling. Listed while selling is on |
danger | Delete 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:
| Field | Type | Description |
|---|---|---|
agents | IConnectedAgent[] | Connected agents - clientId, title, granted scope, lastGrantedAt |
loading | boolean | true while the initial list is loading |
error | string | null | Error message from the last list or revoke, if any |
revoking | string | null | The 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>
);
}| Method | Opens |
|---|---|
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
localeprop onSaaSOSProvider - Responsive - adapts to mobile, tablet, and desktop
- Loading and error states - skeleton loaders, inline errors, retry buttons
Next Steps
- Billing - Subscription plans and checkout.
- Credits - Credit-based billing.
- Internationalization - Locale and RTL support.
- Badge - The "Built with BuildBase" badge and its referral code.
- Connect an AI agent - Add your app's MCP server to the agents your users run.