Gates

A gate answers one question: may this render right now, and if not, what does the user see instead?

There are four, they ask genuinely different questions, and picking the wrong one is how a screen ends up blocked for a reason the user cannot act on.

The access gate

The broad one, and the only one you get without asking — AppShell wraps its children in it.

It covers four unrelated failures that all mean "not right now", and it renders a different, actionable screen for each: a suspended workspace gets a support route, an overdue payment gets a link to billing, pending onboarding gets a link to finish it. That last detail is the reason to use the gate rather than your own if: a blocked screen has to tell the user what to do, and four branches of that are four chances to write a dead end.

import { ConnectAccessGate } from "@cosmoops/connect-sdk/client";

<ConnectAccessGate>
  <Dashboard />
</ConnectAccessGate>

Every state it can be in, on one control — including the two that are easy to forget you have never looked at, the loading frame and the signed-out one:

import { ConnectAccessGate } from "@cosmoops/connect-sdk/client";

<ConnectAccessGate>
  <Dashboard />
</ConnectAccessGate>

The advisory half is separable. ConnectReadinessBanner says what is wrong without blocking anything, which is what a payment retrying inside its grace period deserves — the workspace is still a customer, and the screen still works:

import { ConnectReadinessBanner } from "@cosmoops/connect-sdk/client";

<ConnectReadinessBanner />

Exempting a route

Some routes must render while blocked — the billing page most obviously, since that is where the user goes to unblock themselves.

Declare it on the nav item, next to the route it applies to:

const NAV = [
  { label: "Billing", href: "/billing", icon: <CreditCard className="size-5" />, gateExempt: true },
];

For a route that is in neither nav — a payment callback, say — use gateExemptRoutes, which is prefix-matched the same way:

<AppShell nav={NAV} gateExemptRoutes={["/checkout/callback"]}>
  {children}
</AppShell>

Reading the verdict yourself

When you want the decision but not the default screen:

import { useConnectAccessGate } from "@cosmoops/connect-sdk/client";

const { blocked, reason } = useConnectAccessGate();
if (blocked) return <MyOwnEmptyState reason={reason} />;

The feature gate

Per-feature, read from the subscribed plan's features.

import { ConnectFeatureGate } from "@cosmoops/connect-sdk/client";

<ConnectFeatureGate feature="advanced-reporting" fallback={<UpgradePrompt />}>
  <AdvancedReports />
</ConnectFeatureGate>

The hook form is usually better inside a component that is already rendering — hiding one button does not need a whole gate:

const canExport = useConnectFeature("csv-export");

<Button isDisabled={!canExport}>Export CSV</Button>

import { ConnectFeatureGate } from "@cosmoops/connect-sdk/client";

<ConnectFeatureGate feature="reporting">
  <DeliveryReports />
</ConnectFeatureGate>

The subscription gate

Narrower than the access gate: it asks only about the subscription, ignoring verification, onboarding and payment state.

Reach for it on a screen that is about subscribing — a pricing page, an upgrade flow — where the access gate's "you have no plan" screen would be telling the user something they are already in the middle of fixing.

<ConnectSubscriptionGate fallback={<ConnectPlansPage />}>
  <BillingSettings />
</ConnectSubscriptionGate>

<ConnectSubscriptionGate>
  <BillingSettings />
</ConnectSubscriptionGate>

The workspace-type gate

Some screens only make sense for a team: a members table, seat management, an invite flow. An individual workspace has exactly one seat and can never have another, so those screens are not "empty" for them — they are meaningless.

<ConnectWorkspaceTypeGate type="business" fallback={<ConvertToBusinessPrompt />}>
  <TeamSettings />
</ConnectWorkspaceTypeGate>

A workspace can convert from individual to business under a live session, so read it per render rather than caching it past sign-in.

<ConnectWorkspaceTypeGate type="business" fallback={<ConvertToBusinessPrompt />}>
  <TeamSettings />
</ConnectWorkspaceTypeGate>

Choosing

Walk down this list and stop at the first that fits: