Home/Docs/Badges

Badge Guide

Dynamic status badges for your README files. Choose the right type, theme, and usage pattern.

Badge Types

Health Badge

type=health

Shows overall repository health score with status indicator

Example:health: good (85)

Colors:Green (good), Yellow (fair), Red (poor)

Best for:Primary badge for README files - demonstrates project quality

Stars Badge

type=stars

Displays current star count

Example:stars: 1,234

Colors:Default badge colors

Best for:Show popularity and community interest

Forks Badge

type=forks

Shows number of repository forks

Example:forks: 567

Colors:Default badge colors

Best for:Indicate community adoption and contribution activity

Issues Badge

type=issues

Displays count of open issues

Example:issues: 23

Colors:Yellow (normal), Red (high count >50)

Best for:Show maintenance status and community engagement

Activity Badge

type=activity

Shows development activity level based on commit frequency

Example:activity: high

Colors:Green (high), Yellow (moderate), Red (low)

Best for:Demonstrate ongoing maintenance and development

Theme Categories

Choose themes that match your project's personality and visual style.

Flat

Classic rectangular badges with sharp corners

Style:Traditional, minimal, professional

Best for:Formal documentation, corporate projects

Rounded

Soft rounded corners for a modern look

Style:Contemporary, friendly, approachable

Best for:Open source projects, community-focused repos

Pill

Fully rounded capsule style with extra padding

Style:Bold, prominent, eye-catching

Best for:Featured badges, important status indicators

Minimal

Subtle colors with clean borders

Style:Elegant, understated, sophisticated

Best for:Design-focused projects, minimal themes

Neon

Bright, vibrant colors with bold text

Style:Attention-grabbing, energetic, fun

Best for:Creative projects, gaming, experimental repos

Visual Examples

health + flat

theme=flat

stars + rounded

theme=rounded

activity + pill

theme=pill

issues + minimal

theme=minimal

forks + neon blue

theme=neon-blue

Usage Guidelines

Choose Primary Badge Wisely

Use health badge as your main status indicator - it provides the most comprehensive information

![Health](https://repopulse-one.vercel.app/api/badge?repo=owner/repo&type=health&theme=flat)

Match Theme to Project

Select badge themes that align with your project's personality and target audience

Neon themes for creative projects, minimal themes for professional tools

Use Multiple Badges Strategically

Combine 2-3 badges maximum to avoid cluttering your README

Health + Stars + Activity for comprehensive overview

Consider Readability

Ensure badge text is legible against your README background

Test badges on both light and dark GitHub themes

Keep URLs Current

Use the standard RepoPulse domain for reliable badge delivery

https://repopulse-one.vercel.app/api/badge?repo=owner/repo&type=health

URL Structure

https://repopulse-one.vercel.app/api/badge?repo=owner/repo&type=health&theme=flat

repo:GitHub owner/repository

type:health, stars, forks, issues, activity

theme:flat, rounded, pill, minimal, neon-*

README Integration

Single Badge

<!-- Health Status -->
![Health](https://repopulse-one.vercel.app/api/badge?repo=your-username/your-repo&type=health&theme=flat)

Multiple Badges

<!-- Status Badges -->
![Health](https://repopulse-one.vercel.app/api/badge?repo=owner/repo&type=health&theme=flat)
![Stars](https://repopulse-one.vercel.app/api/badge?repo=owner/repo&type=stars&theme=flat)
![Activity](https://repopulse-one.vercel.app/api/badge?repo=owner/repo&type=activity&theme=flat)

With Themes

<!-- Themed Badges -->
![Health](https://repopulse-one.vercel.app/api/badge?repo=owner/repo&type=health&theme=pill-green)
![Stars](https://repopulse-one.vercel.app/api/badge?repo=owner/repo&type=stars&theme=neon-blue)

Try Badge Themes

Explore all badge types and themes in our interactive gallery. Find the perfect combination for your project.

Badge Gallery All Themes Card Guide

← Cards Guide • Back to Documentation