# Match Card

> A knockout match tile with a flat shape: the time and pitch, an FT or Live badge, and two team rows with kit, score, and the winner's caret.

- Name: `match-card`
- Status: beta
- Categories: sport, display
- File: the install writes `match-card.tsx` to your `ui` alias, `@/components/ui` by default.
- Other registry items: `@arbokui/knockout-bracket`, `@arbokui/team-flag`. The install adds them.
- Gallery: https://arbokui.com/components/match-card
- Registry item: https://arbokui.com/r/match-card.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/match-card
   ```

## Use it for

- A knockout match from data shaped as two teams, each with its own score, like a match day list.
- Pass when as the time and pitch, like "15:20 · Pitch 2".
- Pass status "FT" once it's finished, "Live 9'" while it's on, or leave it out before kick-off.
- At FT the side with the higher score gets the caret. On a level score, pass each side's penalties, and the one with more goes through.
- Pass onClick and selected to make it a match you choose.

## Avoid it for

- A draw of many rounds. Use KnockoutBracket.
- A match that needs a peek with the round's name. Use BracketMatch.
- A league match that can end level. A level FT with no kicks shows no winner, which reads oddly in a cup but is right in a league, so say the result elsewhere.

## Props

- `when`: `string`. The time and pitch, like "15:20 · Pitch 2".
- `status`: `string`. "FT", "Live 9'", or another word like "AET". Left out before kick-off. Any word but Live means it's over.
- `home`: `MatchTeam`. { name, score?, penalties?, colors?, pattern? }. colors are the kit's two colors, as KitColors.
- `away`: `MatchTeam`. The same shape as home.
- `selected`: `boolean`. Default `false`. Draws it as the chosen match. Only a card with onClick can be chosen.
- `onClick`: `() => void`. Makes the card a button that says whether it is pressed.
- `width`: `number`. A fixed width in px, never under 240. By default it fills its column.
- `className`: `string`. Extra classes. Later classes win.

## Accessibility

- The card names both teams and their scores, and says who won in text. The caret and the weight only show it.
- After kicks, it reads FT (P), shows each side's kicks in brackets, and says "won 4–3 on kicks".
- With onClick, it is a button with aria-pressed. A chosen card has a 2px outline that shows in forced colors.
- A Live badge says Live in words. Its red is not the only sign.

## Examples

### Before kick-off

```tsx
<MatchCard when="15:20 · Pitch 2" home={{ name: "QF 3 winner" }} away={{ name: "QF 4 winner" }} />
```

### Finished, after kicks

```tsx
<MatchCard
  when="16:00 · Pitch 1"
  status="FT"
  home={{ name: "Hawks", score: 14, penalties: 3 }}
  away={{ name: "Wolves", score: 14, penalties: 4 }}
/>
```

### Live, and chosen

```tsx
<MatchCard
  when="15:00 · Pitch 1"
  status="Live 9'"
  home={{ name: "Rovers", score: 7, colors: kit, pattern: "hoops" }}
  away={{ name: "Lions", score: 0 }}
  selected={selected === "final"}
  onClick={() => setSelected("final")}
/>
```