Badges

npmx.dev offers many different SVG badges with stats about any package via its API. You can get the Markdown code to display an accessible badge which links to the package URL on npmx.dev with the following interactive generator:

Package Name

Badge Type

VersionLicenseSizeDownloadsDownloads per DayDownloads per WeekDownloads per MonthDownloads per YearVulnerabilitiesDependenciesCreatedUpdatedEnginesTypesMaintainersDeprecatedNameLikes

Preview & Action

Copy

Available Badge Types

• version: Shows the latest or specific version of the package.
• license: Displays the package license (e.g., MIT, Apache-2.0).
• size: Shows the install size (via Bundlephobia) or unpacked size.
• downloads: Displays monthly download statistics.
• downloads-day: Displays daily download statistics.
• downloads-week: Displays weekly download statistics.
• downloads-month: Alias for monthly download statistics.
• downloads-year: Displays yearly download statistics.
• vulnerabilities: Shows the number of vulnerabilities found via OSV. /
• dependencies: Lists the total count of package dependencies.
• created: Displays the date the package was first published.
• updated: Displays the date of the most recent modification.
• engines: Shows the supported Node.js version range.
• types: Indicates if TypeScript types are included. /
• maintainers: Displays the total count of package maintainers.
• deprecated: Shows if the package is active or deprecated. /
• name: Simple badge displaying the package name.
• likes: Shows the total count of package likes.

Examples

# Version Badge

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/version/nuxt)](https://npmx.dev/package/nuxt)

# License Badge

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/license/vue)](https://npmx.dev/package/vue)

# Monthly Downloads

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/downloads/lodash)](https://npmx.dev/package/lodash)

# Scoped Package (Install Size)

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/size/@nuxt/kit)](https://npmx.dev/package/@nuxt/kit)

# Specific Version

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/version/react/v/18.0.0)](https://npmx.dev/package/react)

Compare Badges

Compare badges show how a stat differs between two pinned package versions using a from → to value. They support both same-package comparisons (e.g. how nuxt changed between 2.18.1 and 4.3.1) and cross-package comparisons (e.g. nuxt vs. next). They share the same look, fonts and styles as the regular badges and accept the same customization parameters.

URL pattern

Same-package (shorthand version range):

/api/registry/badge/compare/{type}/{package}/v/{from}...{to}

The version range uses the same triple-dot (...) syntax as the rest of the npmx.dev compare API.

Cross-package (vs separator between two pinned pkg@version specs):

/api/registry/badge/compare/{type}/{pkgA}/v/{verA}/vs/{pkgB}/v/{verB}

In all forms, both versions must already exist on npm — unknown versions return 404.

The badge stays visually compact: only the raw from → to values are rendered, so a cross-package size compare reads 52.7 KB → 200 KB rather than carrying the package names inline. The package context lives in the URL and the SVG aria-label. With name=true the label switches from the strategy name to {pkgA} → {pkgB}, mirroring the regular single-package name=true behavior.

Because the data for two pinned versions is immutable, compare badges are cached for one year (vs. one hour for the regular badges).

Available Compare Badge Types

• version: v{from} → v{to}. Always blue.
• size: install size delta (Bundlephobia, falls back to packument dist.unpackedSize). Color is green when the size shrunk by ≥5%, red when it grew by ≥5%, slate otherwise.
• dependencies: total runtime dependency count delta. Color follows the same direction logic as size (more deps = red, fewer = green).
• license: {from} → {to} license. Green when the license is unchanged across versions, yellow when it changed.
• engines: supported engines.node range. Slate when the supported range is unchanged, yellow when it changed.

Compare-incompatible badge types (name, created, updated, downloads*, maintainers, likes, types, vulnerabilities, deprecated) are not exposed under /badge/compare/... and return 404.

Examples

# Same-package version delta

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/compare/version/nuxt/v/3.0.0...3.21.0)](https://npmx.dev/package/nuxt)

# Same-package install size delta (directional color)

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/compare/size/nuxt/v/3.0.0...3.21.0)](https://npmx.dev/package/nuxt)

# Dependency count delta on a scoped package

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/compare/dependencies/@nuxt/kit/v/3.20.0...3.21.0)](https://npmx.dev/package/@nuxt/kit)

# Cross-package install size comparison

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/compare/size/nuxt/v/4.3.1/vs/next/v/15.5.11)](https://npmx.dev/package/nuxt)

# Cross-package dependencies comparison

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/compare/dependencies/nuxt/v/4.3.1/vs/next/v/15.5.11)](https://npmx.dev/package/nuxt)

# Compact compare badge (e.g. for tight READMEs)

[![Open on npmx.dev](https://npmx.dev/api/registry/badge/compare/dependencies/nuxt/v/3.0.0...3.21.0?style=compact)](https://npmx.dev/package/nuxt)

All Customization Parameters below — label, value, color, labelColor, name, style — work identically on compare badges. A user-supplied color overrides the directional color.

Customization Parameters

You can further customize your badges by appending query parameters to the badge URL.

Use this generator to get the Markdown code you desire:

Package Name

Badge Type

VersionLicenseSizeDownloadsDownloads per DayDownloads per WeekDownloads per MonthDownloads per YearVulnerabilitiesDependenciesCreatedUpdatedEnginesTypesMaintainersDeprecatedNameLikes

Preview & Action

Copy

Label Text

Badge Value

Label Color

#

Badge Color

#

Use package name as label

Badge Styledefaultshieldsiocompact

label

Overrides the default label text. You can pass any string to customize the label displayed on the left half of the badge.

• Default: Depends on the badge type (e.g., "version", "downloads/mo").
• Usage: ?label=YOUR_LABEL

value

Overrides the default value text of the badge. You can pass any string to customize the value displayed on the right half of the badge.

• Default: Calculated values depending on the badge type (e.g., "v4.2.0", "5.4M").
• Usage: ?label=YOUR_LABEL

labelColor

Overrides the default label color. You can pass a standard hex code (with or without the # prefix). The label text color is automatically chosen (black or white) based on WCAG contrast ratio, so the badge remains readable.

• Default: #0a0a0a
• Usage: ?labelColor=HEX_CODE

color

Overrides the default strategy color. You can pass a standard hex code (with or without the # prefix). The text color is automatically chosen (black or white) based on WCAG contrast ratio, so the badge remains readable.

• Default: Depends on the badge type (e.g., version is blue, downloads are orange).
• Usage: ?color=HEX_CODE

name

When set to true, this parameter replaces the static category label (like "version" or "downloads/mo") with the actual name of the package. This is useful for brand-focused READMEs.

• Default: false
• Usage: ?name=true

style

Overrides the badge appearance.

• default — the standard npmx.dev look at 20px tall.
• shieldsio — the classic shields.io-compatible look at 20px tall, useful when you need the badge to sit alongside existing shields.io badges.
• compact — the same modern look and 20px height as default but with tight 5px text padding and no enforced minimum side width. Long built-in labels are also shortened (e.g. install size → size, downloads/mo → dl/mo, dependencies → deps, maintainers → maint) so the badge can take up roughly 20–50% less horizontal space in READMEs. Pass an explicit label or name=true to opt out of the shortening.
• Default: default
• Usage: ?style=compact or ?style=shieldsio