# How to Use the Top Languages Card with Different Layouts (Donut, Pie) in GitHub Readme Stats

> Customize your GitHub Readme Stats top languages card layout with donut and pie options. Easily switch styles using &layout= in the API URL for a better visual representation.

- Repository: [Anurag Hazra/github-readme-stats](https://github.com/anuraghazra/github-readme-stats)
- Tags: how-to-guide
- Published: 2026-02-28

---

**You can switch the visual style of your top languages card by adding `&layout=<name>` to the API URL, choosing from `normal`, `compact`, `donut`, `donut-vertical`, or `pie`.**

The **top languages card** in the `anuraghazra/github-readme-stats` repository renders your most-used programming languages as an SVG image. By default, it displays a vertical list with progress bars, but the underlying renderer supports five distinct visual layouts. This guide explains how to invoke each layout and how the rendering pipeline processes your selection.

## Available Top Languages Card Layouts

The API recognizes five layout values, each handled by a dedicated renderer in [`src/cards/top-languages.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/top-languages.js):

- **`normal`** (default) – Vertical list with language names, colored dots, and horizontal progress bars.
- **`compact`** – Dense vertical list without progress bars; defaults to showing 6 languages.
- **`donut`** – Circular donut chart with a legend positioned to the right.
- **`donut-vertical`** – Larger donut chart with the legend stacked underneath.
- **`pie`** – Classic pie chart with angular slices representing language proportions.

Each layout automatically calculates its own SVG height via dedicated helpers such as `calculateDonutLayoutHeight` and `calculatePieLayoutHeight`.

## How to Change the Layout

Pass the `layout` query parameter to the `/api/top-langs` endpoint. The validation logic in [`api/top-langs.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/top-langs.js) (lines 81‑84) ensures only the five supported values are accepted.

### Markdown Examples for Each Layout

```markdown
<!-- Normal (default) -->
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=octocat)

<!-- Compact -->
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&layout=compact)

<!-- Donut -->
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&layout=donut)

<!-- Donut-vertical -->
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&layout=donut-vertical)

<!-- Pie -->
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&layout=pie)

```

You can combine `layout` with other parameters such as `theme`, `langs_count`, or `hide`:

```markdown
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&layout=donut&theme=radical&langs_count=8)

```

## Technical Implementation Details

The layout selection flows through three main stages:

1. **Parameter validation** ([`api/top-langs.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/top-langs.js)) – The incoming `layout` value is checked against the allowed array `["compact", "normal", "donut", "donut-vertical", "pie"]`.

2. **Default language count** ([`src/cards/top-languages.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/top-languages.js)) – The function `getDefaultLanguagesCountByLayout` assigns different defaults per layout (e.g., 6 for `compact`, 5 for `donut`) to ensure optimal visual balance.

3. **Rendering branch** ([`src/cards/top-languages.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/top-languages.js), lines 390‑426) – The `renderTopLanguages` function switches to the appropriate renderer:

   - `renderPieLayout` – Uses polar-to-cartesian math (`polarToCartesian`, `cartesianToPolar`) to generate SVG path data for pie slices.
   - `renderDonutLayout` / `renderDonutVerticalLayout` – Invoke `createDonutPaths` to build the circular chart and position legends horizontally or vertically.
   - `renderCompactLayout` – Omits progress bars and compresses row height.
   - `renderNormalLayout` – Full list with progress bars.

Each layout calculates its own height via specific helpers (e.g., `calculatePieLayoutHeight`) to prevent clipping.

## Customizing Layout Behavior

### Overriding Default Language Counts

While `getDefaultLanguagesCountByLayout` sets sensible defaults (e.g., 5 languages for donut charts), you can override this with `langs_count`:

```markdown
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&layout=donut&langs_count=10)

```

### Hiding Progress Bars

Setting `hide_progress=true` forces the renderer to use `renderCompactLayout` regardless of the specified layout, because progress bars only render in the normal layout.

### Displaying Raw Bytes

Add `stats_format=bytes` to show absolute byte counts instead of percentages. This works across all layouts including pie and donut.

## Summary

- The **top languages card** supports five layouts: `normal`, `compact`, `donut`, `donut-vertical`, and `pie`.
- Specify your choice via the `layout` query parameter; validation occurs in [`api/top-langs.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/top-langs.js).
- Each layout has dedicated rendering functions in [`src/cards/top-languages.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/top-languages.js) (e.g., `renderPieLayout`, `renderDonutLayout`).
- Default language counts vary by layout to optimize visual presentation, but you can override with `langs_count`.
- Combine `layout` with `theme`, `hide`, or `stats_format` for further customization.

## Frequently Asked Questions

### What layouts are available for the top languages card?

The API supports five layouts: `normal` (default list with progress bars), `compact` (dense list without bars), `donut` (circular chart with side legend), `donut-vertical` (larger donut with bottom legend), and `pie` (classic pie chart with angular slices). Each layout is rendered by a specific function in [`src/cards/top-languages.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/cards/top-languages.js).

### How do I switch to the donut or pie layout?

Append `&layout=donut` or `&layout=pie` to your API URL. For example:

```markdown
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&layout=donut)

```

The validation logic in [`api/top-langs.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/top-langs.js) ensures only supported layout values are processed, and `renderTopLanguages` routes the request to `renderDonutLayout` or `renderPieLayout` accordingly.

### Why does my compact layout show fewer languages by default?

The `getDefaultLanguagesCountByLayout` function assigns different defaults per layout to optimize visual balance. The `compact` layout defaults to 6 languages, while `donut` defaults to 5. You can override this behavior by adding `langs_count=10` (or any number) to your query string.

### Can I combine layout options with themes and other parameters?

Yes. The `layout` parameter works independently of `theme`, `hide`, `langs_count`, and `stats_format`. For example, to render a radical-themed donut chart showing 8 languages with raw byte stats:

```markdown
![Top Langs](https://github-readme-stats.vercel.app/api/top-langs?username=octocat&layout=donut&theme=radical&langs_count=8&stats_format=bytes)

```