> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Categories

> Organize and filter workspaces with reusable category labels — so large teams can navigate dozens of workspaces without scrolling past everything unrelated.

Categories help organizations with a large number of workspaces organize and group them effectively. Once you're running dozens of workspaces, the flat Workspaces list becomes hard to navigate — categories give admins a way to label workspaces by brand, region, team, or lifecycle stage, and give every user a way to filter and sort the list down to just the workspaces they care about.

Think of it as:

* **Workspace** — one project or initiative the team works in
* **Category** — a reusable label admins use to group workspaces together (`Brand: T-Mobile`, `Region: EMEA`, `Q2 Launch`)
* **Workspaces page** — the index where category filtering, search, sort, and pinning come together

Categories are defined once at the org level and reused across every workspace, so the grouping scales as the customer adds more.

## What you can do

When the `workspace-tags` feature is enabled, teams can:

* Apply categories to any workspace, such as `Brand: T-Mobile`, `Region: EMEA`, `Q2 Launch`, or `Compliance Review`
* Filter the Workspaces page by one or more categories from the **Filters → Categories** menu
* Sort the Workspaces table by the Categories column ascending or descending
* Combine categories with the existing search box and status filters (`Pinned`, `Public`, `Private`) to narrow a long list quickly

<Info>
  Managing the org-wide category catalog (rename, delete) is limited to org **Owners** and **Admins** via the **Manage Categories** button on the Workspaces page. Workspace-level Owners and Admins can apply existing categories and create new ones inline from their workspace row.
</Info>

## How it works

<Steps>
  <Step title="Set up the category catalog">
    An org Admin or Owner opens the Workspaces page and clicks **Manage Categories** to create the initial catalog — for example: brand names, regions, or lifecycle stages.
  </Step>

  <Step title="Apply categories to workspaces">
    A workspace Owner or Admin opens the Categories cell on their workspace row and selects one or more existing categories, or types a new name to create one inline.
  </Step>

  <Step title="Filter and sort">
    Anyone with access to the Workspaces page can use the **Filters** dropdown to narrow the list to one or more categories, layer in `Pinned` / `Public` / `Private` status, and sort the Categories column.
  </Step>
</Steps>

Pins and the search box continue to work alongside categories, so a user can pin their most-used workspaces and still slice the rest by category.

## Where search, status, and pins fit

Use categories when you want a stable, reusable label. Use status filters and pins when you want to surface a specific subset within that label.

**Example:**

* Category: `Brand: T-Mobile`
* Status filters: `Pinned`, `Public`, `Private`

That lets a team:

* View every T-Mobile workspace for a portfolio review
* Show only the **pinned** T-Mobile workspaces during a daily standup
* Filter to **Private** T-Mobile workspaces when auditing access
* Use the search box on top of the category filter to jump to a specific workspace name

## Use cases

<AccordionGroup>
  <Accordion title="Multi-brand or multi-business-unit accounts">
    Apply brand categories such as `Brand: T-Mobile`, `Brand: Metro`, or `Brand: Mint` so each team can filter down to just the brand they own.

    This directly solves the "25+ workspaces are unmanageable" problem and lets a brand lead jump straight to their portfolio without scrolling past unrelated work.
  </Accordion>

  <Accordion title="Regional or geo segmentation">
    Create categories like `Region: NA`, `Region: EMEA`, or `Region: APAC` so regional teams can scope the Workspaces page to their geography.

    Useful for global accounts where the same brand spans multiple regions — keeps regional standups and reviews focused on relevant workspaces only.
  </Accordion>

  <Accordion title="Lifecycle and launch tracking">
    Group workspaces by stage such as `In Discovery`, `In Build`, `Launched`, or `Q2 Launch`.

    Gives PMs and CSMs a fast way to pull the "what's shipping this quarter" view, and makes QBRs and launch readiness reviews easier to prep.
  </Accordion>

  <Accordion title="Customer or account-specific organization">
    Create categories per major customer, opportunity, or account team for shared org instances.

    Helps SE and CS teams keep one customer's workspaces visually grouped — useful when one Gradial org supports several end customers or sub-brands.
  </Accordion>

  <Accordion title="Compliance and audit grouping">
    Use categories like `Compliance Review`, `Legal Hold`, or `Restricted` for workspaces with extra governance requirements.

    Lets admins quickly pull every workspace that needs a review pass. Pairs naturally with the existing `Private` status filter for access audits.
  </Accordion>
</AccordionGroup>

## Things to keep in mind

<Warning>
  The Workspace Categories feature must be explicitly enabled per organization (`workspace-tags`). Contact your Gradial team to get access.
</Warning>

* Categories are **org-scoped**, not workspace-scoped — renaming or deleting a category in **Manage Categories** affects every workspace it's applied to.
* Only org-level **Owners** and **Admins** can rename or delete categories from the org catalog. Workspace-level Owners and Admins can apply existing categories and create new ones inline.
* Category names are capped at **120 characters**.
* A single filter selection caps at **50 active values**.
* Categories work alongside the existing search box, status filters, and pinning behavior — they complement pins, not replace them.