On this page
@addTagHelper *, Webority.Ui.RazorThe switcher
The card shows the current workspace, and its menu lists the ones the person can reach, with the active row tinted.
Monogram or logo
Each workspace shows its logo when one is set, otherwise a monogram from the first two words of its name.
Badges
A short badge, such as the person's role or the plan, sits at the end of a workspace row before the tick.
Compact
A 36px monogram trigger suits a collapsed sidebar rail, and the menu is unchanged.
Sizes
Use sm in a dense topbar or filter bar, md by default, and lg for a roomy sidebar header.
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.
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
(default): no filter box
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
The current workspace is named on the trigger, ticked in the list, and settings are one row away.
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
Eight workspaces get a filter box, so finding one is typing rather than scrolling.
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.
13 props. The 4 most used come first.
Used on most screens 4 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| (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 pairsName the current workspace
The current workspace is named on the trigger, ticked in the list, and settings are one row away.
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
Eight workspaces get a filter box, so finding one is typing rather than scrolling.
Three workspaces behind a search box: a control to skip past on the way to something already visible.