# How to Use the Awesome Badge on Your Project's List

> Learn how to add the awesome badge to your project list. Embed the official SVG image and link to awesome.re for increased visibility and credibility.

- Repository: [Sindre Sorhus/awesome](https://github.com/sindresorhus/awesome)
- Tags: how-to-guide
- Published: 2026-07-07

---

**To add the awesome badge to your open source list, embed one of the three official SVG images hosted on awesome.re and wrap it in a markdown hyperlink pointing to `https://awesome.re`.**

The sindresorhus/awesome repository maintains the canonical standards for Awesome lists through its [`awesome.md`](https://github.com/sindresorhus/awesome/blob/main/awesome.md) file. Displaying the **awesome badge** signals to readers that your repository follows the Awesome list format and provides a direct navigation path back to the main Awesome website.

## Where the Badge Is Defined

The official badge definitions and usage guidelines reside in [`awesome.md`](https://github.com/sindresorhus/awesome/blob/main/awesome.md) under the "## Awesome badge" section. This file specifies the exact image URLs, permitted variants, and placement rules that maintain visual consistency across the Awesome ecosystem.

According to the source code, the badge must link to `https://awesome.re` and cannot be modified or recreated—you must use the provided image assets exactly as hosted.

## Available Badge Styles

The sindresorhus/awesome repository provides three approved visual variants. Each uses a different SVG file hosted on the awesome.re domain:

- **Regular badge** – The default rectangular version with subtle depth
- **Flat badge** – A modern, flat-design alternative without gradients  
- **Flat-2 badge** – A slightly different flat variation with adjusted proportions

All three variants identify your list equally; choose based on your README's visual aesthetic.

## Implementation Steps

To correctly implement the awesome badge in your repository:

1. Open your repository's [`README.md`](https://github.com/sindresorhus/awesome/blob/main/README.md) file.

2. Position the badge markdown immediately after your H1 title, either on the same line or the next line.

3. Select your preferred badge URL from the three official options:
   - `https://awesome.re/badge.svg`
   - `https://awesome.re/badge-flat.svg`
   - `https://awesome.re/badge-flat2.svg`

4. Wrap the image in a link to `https://awesome.re` using standard markdown syntax.

5. Do not resize, recolor, or otherwise alter the badge image.

The badge requires no CI configuration, API tokens, or build steps—it functions as a static markdown element.

## Code Examples

Here are the complete markdown snippets for each badge style. Place these right after your list title:

**Standard badge:**

```markdown

# Awesome MyProject List

[![Awesome](https://awesome.re/badge.svg)](https://awesome.re)

A curated collection of …

```

**Flat style:**

```markdown

# Awesome MyProject List

[![Awesome](https://awesome.re/badge-flat.svg)](https://awesome.re)

```

**Flat-2 variant:**

```markdown

# Awesome MyProject List

[![Awesome](https://awesome.re/badge-flat2.svg)](https://awesome.re)

```

## Guidelines and Requirements

When using the awesome badge, adhere to these rules defined in the source repository:

- **No alterations**: You must not modify the badge colors, dimensions, or file contents. Use the SVG files exactly as hosted on awesome.re.
- **Mandatory link**: The badge must hyperlink to `https://awesome.re`, not to your own repository or a fork of the Awesome list.
- **Checklist verification**: The [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) in sindresorhus/awesome explicitly mentions the badge as a checklist item for contributors, confirming that submitted lists include the required badge before review.

## Summary

- The awesome badge specifications live in [`awesome.md`](https://github.com/sindresorhus/awesome/blob/main/awesome.md) under the "## Awesome badge" section.

- Choose from three unmodified SVG variants: regular, flat, or flat-2.
- Embed the badge immediately after your README title using markdown image syntax wrapped in a link to `https://awesome.re`.
- No configuration tokens or build steps are required to display the badge.
- The badge appears as a verification item in [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) for new Awesome list submissions.

## Frequently Asked Questions

### Can I customize the colors of the awesome badge?

No, you cannot customize the badge appearance. According to the guidelines in [`awesome.md`](https://github.com/sindresorhus/awesome/blob/main/awesome.md), the badge must not be altered in any way. You must use the official SVG files hosted at awesome.re exactly as provided, without recoloring, resizing, or modifying the image files.

### Where exactly should I place the badge in my README?

Place the awesome badge immediately after your main H1 title. According to the sindresorhus/awesome source code, the badge typically appears on the same line as the title or on the line directly below it, before the introductory paragraph of your list.

### Do I need to install any dependencies or packages to use the badge?

No dependencies are required. The awesome badge is a static markdown image link that references SVG files hosted on `https://awesome.re`. You do not need API keys, CI tokens, npm packages, or any build configuration to implement it—simply paste the markdown code into your README.

### Which badge style should I choose for my list?

Any of the three official styles—regular, flat, or flat-2—are acceptable according to the sindresorhus/awesome repository. The choice depends entirely on your visual preference and which variant best matches your README's design aesthetic. All three variants link to the same destination and carry identical semantic weight.