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

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:

• 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 (lines 81‑84) ensures only the five supported values are accepted.

Markdown Examples for Each Layout

<!-- 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:

![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) – 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) – 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, 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:

![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.
• Each layout has dedicated rendering functions in 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.

How do I switch to the donut or pie layout?

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

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

The validation logic in 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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}