# Standings

> A league table or a tournament pool, on DataTable: the place, the team and its kit, the counts, points difference, points, and form, with zones.

- Name: `standings`
- Status: beta
- Categories: sport, display
- File: the install writes `standings.tsx` to your `ui` alias, `@/components/ui` by default.
- Other registry items: `@arbokui/data-table`, `@arbokui/form-guide`, `@arbokui/team-flag`. The install adds them.
- Gallery: https://arbokui.com/components/standings
- Registry item: https://arbokui.com/r/standings.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/standings
   ```

## Use it for

- A league table or a tournament pool. Put it in a Card with className="px-0", and name it with the card's title through aria-labelledby.
- The app works out the numbers and the order. The table only shows them.
- layout league shows P W D L PD BP Pts. pool shows P W D L PF PA PD Pts.
- zones mark places that mean something: promotion from the top in success, relegation from the bottom in danger. Give each a note, so its peek says what it means.
- you marks your team: a blue bar, its own wash, and its name in the strong weight.
- In a narrow card the counts give way, PF and PA first, then form, then D and BP, and under 20rem W and L, so the team keeps its room.

## Avoid it for

- A row inserted between zones. A zone's edge is its 2px rule.
- Real club colors in a demo. Pass theme tokens, like var(--chart-1).
- Ranking people. Use Leaderboard.

## Props

- `rows`: `StandingsRow[]`. Required, in table order. Each: { id, team: { name, colors?: KitColors, pattern? }, position?, played, won, drawn, lost, pointsFor?, pointsAgainst?, diff?, bonus?, points, form?: FormResult\[\] }.
- `layout`: `"league" | "pool"`. Default `"league"`. Which counts show.
- `you`: `string`. Your team's id.
- `zones`: `{ label: string; top?: number; bottom?: number; tone?: "success" | "danger" | "warning" | "brand"; note?: string }[]`. Places counted from the top or the bottom. tone defaults to success from the top and danger from the bottom.
- `form`: `boolean`. Default `true`. The form column, when any row has form.
- `caption`: `ReactNode`. Names the table, under it.
- `aria-label`: `string`. Names the table when it has no caption.
- `aria-labelledby`: `string`. Names the table by another element, like the Card's title.
- `loading`: `boolean`. Default `false`. Holds the space with placeholder rows.
- `className`: `string`. Extra classes on the wrapper. Later classes win.

## Accessibility

- A real \<table>. Each team's name is the row header, so every count is read with it.
- Short headers, like P, are read as their full words, like Played, and show them on a mouse rest.
- A zone's place number is read with its label, like "1, Promotion". Its peek says what the zone means.
- Points difference uses a true minus sign, which screen readers read as minus.
- A zone's edges and your team's bar are borders, so they stay in forced colors.

## Examples

### League with promotion and relegation zones

```tsx
<Standings
  aria-label="League"
  you="rov"
  zones={[
    { label: "Promotion", top: 1, note: "The top team goes up." },
    { label: "Relegation", bottom: 1, note: "The bottom team goes down." },
  ]}
  rows={[
    { id: "lio", team: { name: "Lions", colors: ["var(--chart-1)", "var(--background)"] }, played: 10, won: 8, drawn: 0, lost: 2, diff: 96, bonus: 6, points: 38 },
    { id: "rov", team: { name: "Rovers", colors: ["var(--foreground)", "var(--chart-3)"], pattern: "hoops" }, played: 10, won: 6, drawn: 1, lost: 3, diff: 41, bonus: 5, points: 31 },
    { id: "fal", team: { name: "Falcons" }, played: 10, won: 1, drawn: 1, lost: 8, diff: -120, bonus: 2, points: 8 },
  ]}
/>
```