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

# Lap Counter and Laps To Go

> Two large single-line readouts of how far the race has run and how far it has left, as of the playhead.

## Overview

Lap Counter and Laps To Go are two small widgets that each show one big line of text: **Lap Counter** reads "Current Lap: X of Y" and **Laps To Go** reads "Laps to go: X". They are built to be read from across the room, so the text scales with the tile and a tile can be dragged large on a spare screen. Both measure the playhead lap against the scheduled race distance.

> [!NOTE]
>
> Both are race-only widgets: outside a race session each shows "Session is not a race." and computes nothing.

***

## What It Shows

![Lap Counter and Laps To Go side by side (Singapore 2026, lap 42)](https://mintcdn.com/smedley_group/C2dbdruF7PmauGL8/images/watchparty/lap-counter.png?fit=max\&auto=format\&n=C2dbdruF7PmauGL8\&q=85\&s=1e40f45bb88cb59eba575de6f5cf1d13)

Each widget is a single centred line in a bold, fixed-width, tabular font, so the digits do not jitter as the lap changes. The font size follows the tile's height and width, so the line grows and shrinks with the window rather than being fixed. The line never wraps.

### Lap Counter

| Element | Meaning |
| - | - |
| Current Lap | The lap the playhead is on |
| of Y | The scheduled race distance in laps |
| Dash | Shown in place of the lap number before the first lap has started |

If the playhead lap ever exceeds the total, the lap shown is held at the total, so the line never reads past "57 of 57".

### Laps To Go

| Element | Meaning |
| - | - |
| Laps to go | The race distance minus the playhead lap, never below zero |
| Dash | Shown in place of the number when the race distance is not known |

Before the first lap the full distance is shown. After the flag it holds at 0.

***

## Data Behind It

Neither widget has an insight metric behind it, so there is no `model_id` or `model_version` to read. Both are client-side derivations: `currentLapText` and `lapsToGoText` in `src/screens/lapCounterText.ts` build the strings, and `LapCounter` and `LapsToGo` in `src/screens/LapCounter.tsx` draw them.

* **Playhead lap**: the same current lap the transport bar shows, so both widgets move with play, pause, seek and scrub.
* **Race distance**: the `total_laps` value of the race's `fuel_numbers` parameter row, fetched once from the gateway's parameters endpoint when the session is opened and matched to the session's season and round.
* **No fallback**: the transport bar falls back to the highest lap seen so far when the parameter is missing. These two widgets deliberately do not use that fallback, because it would make "Current Lap: 12 of 12" read as true mid-race. With no parameter they say less, or show a dash, rather than guess.
* Live and replay envelopes are wire-identical; the widgets never branch on envelope `source`.

***

## States

> **Normal race running**
>
> Lap Counter reads "Current Lap: 12 of 57" and Laps To Go reads "Laps to go: 45".

> **Before the first lap**
>
> Lap Counter reads "Current Lap: - of 57". Laps To Go shows the whole distance, "Laps to go: 57".

> **Race distance unknown**
>
> Lap Counter drops the total and reads "Current Lap: 12". Laps To Go reads "Laps to go: -". This happens when the race has no `fuel_numbers` row, or the row carries no total, or the session is not yet matched to a season and round.

> **Before the first lap and distance unknown**
>
> Lap Counter reads "Current Lap: -".

> **Playhead past the distance**
>
> Lap Counter holds at the total, for example "Current Lap: 57 of 57". Laps To Go reads "Laps to go: 0".

> **Not a race**
>
> In practice, qualifying or any other non-race session, both widgets show "Session is not a race."

> **Live vs replay**
>
> Identical rendering; only the playhead differs.

***

## FAQ

> **Why does the transport bar show a total but Lap Counter does not?**
>
> The transport bar falls back to the highest lap observed so far when the race distance is missing. These widgets read the scheduled distance only, so they leave the total out rather than show an observed count that would be wrong mid-race.

> **Why does Laps To Go show a dash?**
>
> The race distance is not available for this session. Nothing is assumed, so there is no number to subtract from.

> **Does Laps To Go change after a red flag or a shortened race?**
>
> No. It uses the scheduled distance from the parameter row and the playhead lap, so it does not adjust for a race that finishes early or on time.

> **Can I make the text bigger?**
>
> Yes. Resize the tile and the text scales with it, up to a very large size.

***

## Next Steps

> **[Timing Tower](/software/internal/watchparty/widgets/timing-tower)**
>
> The running order that goes with the lap count.

> **[Pit Stops](/software/internal/watchparty/widgets/pit-stops)**
>
> Who has stopped, and when, as the laps run down.

> **[Pit Window](/software/internal/watchparty/widgets/pit-window)**
>
> The stop window measured against the laps remaining.

> **[Tyre Deg & Life](/software/internal/watchparty/widgets/tyre-deg-life)**
>
> How much tyre is left for the laps to go.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.