Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

The switcher

The card shows the current workspace, and its menu lists the ones the person can reach, with the active row tinted.

Current workspace plus a menu
compact is a shape switch, not a resize: the trigger is a full-width card unless compact is on, so it fills whatever slot it is dropped into. Constrain the container, not the component. Each option is one app-workspace-option: value is what current-id matches, name is the label and the source of the monogram, logo-src replaces the monogram, and badge adds a short trailing pill.
Show code
<app-workspace-switcher current-id="acme">
    <app-workspace-option value="acme" name="Acme Corp" badge="Owner" />
    <app-workspace-option value="globex" name="Globex Ltd" logo-src="/img/sample-logo.png" href="/switch/globex" />
    <app-workspace-option value="initech" name="Initech" href="/switch/initech" />
</app-workspace-switcher>
A filter over a long list
Past roughly eight workspaces a list stops being scannable. searchable adds a filter box above it that narrows the rows as the user types. With three workspaces the filter is a control the user has to skip past to reach rows they can already see, so leave it off until the list is long.
Show code
<app-workspace-switcher current-id="acme" searchable="true" menu-label="Workspaces">
    <app-workspace-option value="acme" name="Acme Corp" badge="Owner" />
    <app-workspace-option value="globex" name="Globex Ltd" href="/switch/globex" />
    …
</app-workspace-switcher>
Empty trigger and empty note
With no app-workspace-option children the trigger has nothing to show, and the menu carries only its empty note.
Show code
<app-workspace-switcher current-id="acme"></app-workspace-switcher>

Monogram or logo

Each workspace shows its logo when one is set, otherwise a monogram from the first two words of its name.

A logo replaces the monogram
How the monogram is built: “Wayne Heavy Industries” draws WH (the first two words, later words ignored), a one-word “Initech” draws I, and “Acme Corp” draws A because company words such as Corp, Pvt and Ltd are skipped. The React component computes the same letters, so a workspace looks identical on both surfaces.
Show code
<app-workspace-switcher current-id="globex">
    <app-workspace-option value="acme" name="Acme Corp" href="/switch/acme" /> <!-- monogram A (Corp is skipped) -->
    <app-workspace-option value="globex" name="Globex Ltd" logo-src="/img/sample-logo.png" />
</app-workspace-switcher>

Badges

A short badge, such as the person's role or the plan, sits at the end of a workspace row before the tick.

A role badge on the owned workspace
The row already holds a mark, a name and a tick. “Owner”, “Trial”, “Pro” fit; a sentence truncates the name it is meant to qualify.
Show code
<app-workspace-switcher current-id="acme" menu-label="Workspaces">
    <app-workspace-option value="acme" name="Acme Corp" badge="Owner" />
    <app-workspace-option value="globex" name="Globex Ltd" href="/switch/globex" />
</app-workspace-switcher>

Compact

A 36px monogram trigger suits a collapsed sidebar rail, and the menu is unchanged.

The collapsed-rail trigger
Show code
<app-workspace-switcher current-id="acme" compact="true">
    <app-workspace-option value="acme" name="Acme Corp" badge="Owner" />
</app-workspace-switcher>

Sizes

Use sm in a dense topbar or filter bar, md by default, and lg for a roomy sidebar header.

Three sizes
A larger size grows the card and its monogram, but the workspace list stays the same 280px panel. Pair size with compact and the square scales too (32 / 36 / 44px).
Small
Medium
Large
Show code
<app-workspace-switcher current-id="acme" size="Sm" menu-label="Workspaces">…</app-workspace-switcher>
<app-workspace-switcher current-id="acme" menu-label="Workspaces">… <!-- md (default) --></app-workspace-switcher>
<app-workspace-switcher current-id="acme" size="Lg" menu-label="Workspaces">…</app-workspace-switcher>

The create row

can-create pins a “create workspace” row under the list. With create-href it navigates; without one it renders a button carrying data-workspace-create for the page's own handler. It is off by default because most members cannot create a workspace, so show it only when the signed-in user actually has that permission.

Create plus a pinned footer action
Set can-create from the same permission check the create endpoint enforces. A visible row the server rejects is worse than no row.
Show code
<app-workspace-switcher current-id="acme" can-create="true" create-label="Create workspace">
    <app-workspace-option value="acme" name="Acme Corp" badge="Owner" />
    <app-workspace-option value="globex" name="Globex Ltd" href="/switch/globex" />
    <app-workspace-footer>
        <a class="workspace-switcher-footer-action" href="/settings">Workspace settings</a>
    </app-workspace-footer>
</app-workspace-switcher>

Every option

Every value of every prop, one cell each.

tenants

(no <app-workspace-option> children): empty trigger, empty note
one <app-workspace-option>: one row, no footer
name only: monogram from the first two words
logo-src set: the logo replaces the monogram
badge set: a short pill on the row

currentId

current-id="acme" (default)
current-id="globex"
current-id="initech"

onSelect

onSelect (React only): Razor follows each option's href, so a row pick navigates

menuLabel

(default): no heading
menu-label="Workspaces"

footerAction, or the app-workspace-footer slot on Razor

(default): no app-workspace-footer, footer omitted entirely
node (React only): rendered as is; Razor writes the markup in the slot
{ label }: a button in the slot
{ label, icon, href }: a plain anchor in the slot

linkComponent

linkComponent (React only): write your router link inside the slot

searchable

searchable="true": filter box above the list

searchPlaceholder

(default): placeholder "Search workspaces"
search-placeholder="Find a company"

searchLabel

(default): accessible label "Search workspaces"
search-label="Find a company"

noMatchText

(default): "No workspaces match." when the filter finds nothing
no-match-text="Nothing found": shown when the filter finds no workspace

canCreate

(default): no create row
can-create="true": default label

createLabel

(default): "Create workspace"
create-label="New tenant"

onCreate

onCreate (React only): Razor renders a button with data-workspace-create for the page's handler

create-href (Razor only)

(default): no create-href, the row is a button
create-href="/workspaces/new": the row navigates there

compact

(default): full card
compact="true": 36px monogram button

size

size="sm"
size="md" (default)
size="lg"

ariaLabel (Razor: aria-label)

aria-label="Switch company": names the trigger for screen readers

Guidance

What to do, and what to avoid.

Use it when

  • A user can belong to more than one workspace, tenant, organisation, or company.
  • The current workspace must stay visible so a user never acts in the wrong one.
  • The sidebar or topbar needs one place to switch tenant and reach workspace settings.

Reach for something else when

  • You are switching the signed-in USER, not the workspace. → AppDropdown
  • You are picking a value into a form field. → AppSelect
  • You need a flat list of actions behind a “⋯” trigger. → AppDropdown
  • You are navigating within one workspace. → AppShell

Name the current workspace

Do

The current workspace is named on the trigger, ticked in the list, and settings are one row away.

Avoid

A compact trigger in a full-width sidebar hides the workspace name, the one thing the control exists to show. Save it for a collapsed rail.

Filter only a long list

Do

Eight workspaces get a filter box, so finding one is typing rather than scrolling.

Avoid

Three workspaces behind a search box: a control to skip past on the way to something already visible.

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

acme globex initech
sm md lg
React, generated from the controls
<AppWorkspaceSwitcher
  tenants={tenants}
  currentId="acme"
  onSelect={(tenant) => switchWorkspace(tenant.id)}
/>
Razor, the same props
<app-workspace-switcher current-id="acme">
    <app-workspace-option value="acme" name="Acme Corp" badge="Owner" href="/switch/acme" />
    <app-workspace-option value="globex" name="Globex Ltd" href="/switch/globex" />
    <app-workspace-option value="initech" name="Initech" href="/switch/initech" />
</app-workspace-switcher>

13 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
current-iddefault first option string first option The id of the active workspace. It drives the trigger and the tick, and falls back to the first workspace when it matches none.
menu-labeldefault - string - An optional heading above the list, such as Workspaces.
searchabledefault false bool false Adds a filter box above the list. It only earns its place past roughly eight workspaces.
can-createdefault false bool false Shows the create row. It is off by default because most members cannot create a workspace.

Less common 9 props

PropTypeDefaultDescription
(content)default - markup - The workspaces: one <app-workspace-option> each, plus an optional <app-workspace-footer> slot.
create-labeldefault Create workspace string Create workspace The text of the create row.
create-hrefdefault - string - Where the create row navigates. Without it the row is a button carrying data-workspace-create.
compactdefault false bool false Draws a 36px monogram button instead of the full card, the shape a collapsed rail slot wants. The menu is the same either way.
sizedefault md sm | md | lg md Scales the trigger (the card or compact square, its mark and name) and the menu (width, row padding, avatars, the create plus chip and the footer), so trigger and panel read at one size.
aria-labeldefault Workspace <name> string Workspace <name> The accessible name of the trigger. Without it the name is Workspace followed by the current workspace's name.
search-placeholderdefault Search workspaces string Search workspaces Replaces the built-in English text, for other languages.
search-labeldefault Search workspaces string Search workspaces Replaces the built-in English text, for other languages.
no-match-textdefault No workspaces match. string No workspaces match. Replaces the built-in English text, for other languages.

Screen reader

4 notes
  • The trigger is a native button with aria-haspopup, named by ariaLabel or, without it, Workspace followed by the current name; the compact trigger keeps the full name.
  • Rows are native buttons in a dropdown menu, so Tab and the arrow keys reach them and Escape closes the menu.
  • The filter box is named Search workspaces; while typing, the arrow keys stay with the text, and Escape closes the menu.
  • Logos carry an empty alt, so each workspace name is read once.

Do and avoid

2 pairs

Name the current workspace

Do

The current workspace is named on the trigger, ticked in the list, and settings are one row away.

Avoid

A compact trigger in a full-width sidebar hides the workspace name, the one thing the control exists to show. Save it for a collapsed rail.

Filter only a long list

Do

Eight workspaces get a filter box, so finding one is typing rather than scrolling.

Avoid

Three workspaces behind a search box: a control to skip past on the way to something already visible.