Multi-Tenancy

TenantProvider gives your app tenant switching: list tenants, switch between them, auto-resolve the default, and track loading state. Wrap your app (inside AuthProvider), use useTenant() to read state, and drop in TenantSwitcher for a ready-made UI — or build your own.

Quick start

1. Wrap your app

TenantProvider must be inside AuthProvider. Pass the SDK methods generated by codegen:

import { AuthProvider, TenantProvider } from '@vertz/ui-auth';
import { auth } from './.vertz/generated/auth';

function App() {
  return (
    <AuthProvider>
      <TenantProvider
        listTenants={auth.listTenants}
        switchTenant={auth.switchTenant}
        onSwitchComplete={(tenantId) => {
          // Navigate, refetch data, etc.
          navigate({ to: '/dashboard' });
        }}
      >
        <AppContent />
      </TenantProvider>
    </AuthProvider>
  );
}

2. Drop in the switcher

import { TenantSwitcher } from '@vertz/ui-auth';

function Sidebar() {
  return (
    <nav>
      <TenantSwitcher />
    </nav>
  );
}

3. Or build a custom UI with the hook

import { useTenant } from '@vertz/ui-auth';

function CustomTenantPicker() {
  const { tenants, currentTenantId, switchTenant, isLoading } = useTenant();

  if (isLoading) return <div>Loading tenants...</div>;

  return (
    <div>
      {tenants.map((tenant) => (
        <button
          key={tenant.id}
          onClick={() => switchTenant(tenant.id)}
          data-active={tenant.id === currentTenantId ? 'true' : undefined}
        >
          {tenant.name}
        </button>
      ))}
    </div>
  );
}

TenantProvider

Fetches the tenant list on mount and provides tenant state to all children via context.

<TenantProvider
  listTenants={auth.listTenants}
  switchTenant={auth.switchTenant}
  onSwitchComplete={(tenantId) => {
    /* ... */
  }}
>
  <App />
</TenantProvider>

Prop	Type	Description
`listTenants`	`() => Promise<Result<ListTenantsResponse>>`	SDK method to fetch tenants (generated by codegen)
`switchTenant`	`SdkMethod<{ tenantId: string }>`	SDK method to switch tenant (generated by codegen)
`onSwitchComplete`	`(tenantId: string) => void`	Called after a successful switch — use for navigation
`children`	`unknown`	App content

TenantProvider must be rendered inside AuthProvider. It reads from AuthContext internally — you don’t need to pass auth state manually.

Automatic query invalidation on tenant switch

When switchTenant() succeeds, all active tenant-scoped queries are automatically invalidated. Cached data from the previous tenant is cleared immediately (no stale cross-tenant data visible), then each query refetches with the new tenant context. Non-tenant-scoped queries (e.g., global settings) are left untouched. This happens automatically — no manual invalidation or onSwitchComplete callback needed for data freshness.

useTenant()

Returns reactive tenant state. All signal properties are auto-unwrapped by the compiler.

const tenant = useTenant();

Property	Type	Description
`tenants`	`TenantInfo[]`	All tenants the user belongs to
`currentTenantId`	`string \| undefined`	Tenant in the current session
`lastTenantId`	`string \| undefined`	Last tenant the user switched to
`resolvedDefaultId`	`string \| undefined`	Server-recommended default tenant
`isLoading`	`boolean`	`true` while fetching tenants
`switchTenant`	`(tenantId: string) => Promise<Result<void, Error>>`	Switch to a different tenant

TenantInfo

interface TenantInfo {
  id: string;
  name: string;
  [key: string]: unknown; // logo, plan, role — whatever you return from listTenants
}

TenantSwitcher

A ready-made dropdown component that renders the current tenant with a menu to switch. Import from @vertz/ui-auth:

import { TenantSwitcher } from '@vertz/ui-auth';

<TenantSwitcher
  renderItem={(tenant) => (
    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
      <img src={tenant.logo} width={20} height={20} />
      <span>{tenant.name}</span>
    </div>
  )}
  className="my-tenant-picker"
/>;

Prop	Type	Default	Description
`renderItem`	`(tenant: TenantInfo) => unknown`	Renders `tenant.name`	Custom render for each tenant item (trigger and dropdown)
`className`	`string`	—	CSS class for the container

Styling

TenantSwitcher uses data-part attributes for styling:

Part	Element	Description
`tenant-switcher`	Container `div`	Root wrapper
`trigger`	`button`	Shows the current tenant
`content`	`div`	Dropdown panel
`item`	`button`	Individual tenant option

Items have data-selected="true" when they match the current tenant.

[data-part='tenant-switcher'] {
  position: relative;
}
[data-part='trigger'] {
  /* trigger button styles */
}
[data-part='content'] {
  /* dropdown styles */
}
[data-part='item'] {
  /* item styles */
}
[data-part='item'][data-selected] {
  /* selected item styles */
}

When a user logs in, their session has no tenantId. The resolvedDefaultId from useTenant() tells you which tenant the server recommends — typically the last-accessed tenant. Use this to auto-switch on app mount:

import { useTenant } from '@vertz/ui-auth';
import { watch } from '@vertz/ui';

function TenantAutoResolver() {
  const { resolvedDefaultId, currentTenantId, switchTenant, isLoading } = useTenant();

  watch(
    () => isLoading,
    (loading) => {
      if (!loading && resolvedDefaultId && !currentTenantId) {
        switchTenant(resolvedDefaultId);
      }
    },
  );

  return null;
}

Place this inside TenantProvider. After the tenant list loads, it auto-switches to the resolved default if no tenant is currently selected.

Common patterns

Tenant name in header

function Header() {
  const { tenants, currentTenantId } = useTenant();
  const current = tenants.find((t) => t.id === currentTenantId);

  return (
    <header>
      <span>{current?.name ?? 'No tenant selected'}</span>
    </header>
  );
}

Redirect after switch

<TenantProvider
  listTenants={auth.listTenants}
  switchTenant={auth.switchTenant}
  onSwitchComplete={() => {
    // Redirect to dashboard after switching
    navigate({ to: '/dashboard' });
  }}
>

With custom avatars per tenant

<TenantSwitcher
  renderItem={(tenant) => (
    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
      <Avatar src={tenant.logo} fallback={tenant.name[0]} size="sm" />
      <span>{tenant.name}</span>
    </div>
  )}
/>

Server setup

The client-side tenant features require server-side configuration. See the server multi-tenancy guide for:

Configuring tenant.verifyMembership, tenant.listTenants, and tenant.resolveDefault
How tenant-scoped JWTs work
Automatic entity tenant scoping
Endpoint reference

Next steps

Server Multi-Tenancy

Configure tenant endpoints, membership verification, and auto-resolve.

Authentication

AuthProvider, useAuth(), and session management.

Access Control

Entitlements and tenant-scoped access rules.

Getting Started

@vertz/ui

@vertz/ui-compiler

@vertz/icons

@vertz/schema

@vertz/errors

@vertz/server

@vertz/agents

@vertz/db

@vertz/desktop

@vertz/fetch

@vertz/openapi

Deployment

Testing

Runtime

Multi-Tenancy

Quick start

1. Wrap your app

2. Drop in the switcher

3. Or build a custom UI with the hook

TenantProvider

Automatic query invalidation on tenant switch

useTenant()

TenantInfo

TenantSwitcher

Styling

Common patterns

Tenant name in header

Redirect after switch

With custom avatars per tenant

Server setup

Next steps

Server Multi-Tenancy

Authentication

Access Control

​Quick start

​1. Wrap your app

​2. Drop in the switcher

​3. Or build a custom UI with the hook

​TenantProvider

​Automatic query invalidation on tenant switch

​useTenant()

​TenantInfo

​TenantSwitcher

​Styling

​Auto-resolve on login

​Common patterns

​Tenant name in header

​Redirect after switch

​With custom avatars per tenant

​Server setup

​Next steps

Server Multi-Tenancy

Authentication

Access Control

Quick start

1. Wrap your app

2. Drop in the switcher

3. Or build a custom UI with the hook

TenantProvider

Automatic query invalidation on tenant switch

useTenant()

TenantInfo

TenantSwitcher

Styling

Auto-resolve on login

Common patterns

Tenant name in header

Redirect after switch

With custom avatars per tenant

Server setup

Next steps