# League widget

> Seasonal tier standing — live cohort board, promotion target, and Boss Fight progress.

Source: https://docs.hatched.live/docs/reference/widgets/league

## Mount

```html
<script src="https://cdn.hatched.live/widget.js" data-embed-token="EMBED_TOKEN" defer></script>

<div data-hatched-mount="league"></div>
```

The League widget is read-only, so an embed token is enough.

## Script attributes

| Attribute            | Values                 | Default                           |
| -------------------- | ---------------------- | --------------------------------- |
| `data-embed-token`   | embed token            | read-only                         |
| `data-session-token` | widget session token   | read-only                         |
| `data-theme`         | `light` `dark`         | `light`                           |
| `data-api-base-url`  | API origin + `/api/v1` | `https://api.hatched.live/api/v1` |

## Required scopes

- `read` renders the tier banner, cohort standings and Boss Fight progress.

## Plan & capability

- Capability: `leagues` (plan entitlement + a tenant toggle in Settings →
  Capabilities; on by default).
- Minimum plan: **Growth**. The capability is enforced at the controller, so:
  - When the plan does not entitle LEAGUES the endpoints return
    `403 plan_feature_locked`.
  - When the tenant has switched the `leagues` toggle off the endpoints return
    `403 capability_disabled`.
  - When entitled and enabled but no season is running (or the buddy is not
    enrolled) the endpoints return an `available: false` snapshot and the
    widget renders nothing.

## Endpoints

| Method | Path                        | Purpose                                          |
| ------ | --------------------------- | ------------------------------------------------ |
| `GET`  | `/widget/leagues/me`        | Live tier, cohort standings, promotion target, demotion flag |
| `GET`  | `/widget/leagues/boss-fight`| Season Boss Fight challenge — progress, target, leaderboard |