---
title: 'Levels, Ranks & Medals'
url: 'https://manuals.remository.com/userpoints/levels-ranks-medals'
markdown: 'https://manuals.remository.com/userpoints/levels-ranks-medals.md'
date: '2026-10-06'
description: 'UserPoints supports two forms of user recognition: ranks (also called levels), which are tiers users advance through as they accumulate points, and medals (also called badges), which are one-off achievements awarded for specific milestones. Both are managed from Components → UserPoints → Level Rank…'
taxonomy:
  category:
    - docs
---

[](#) [ edit this page](https://github.com/getgrav/grav-skeleton-rtfm-site/blob/develop/pages/07.levels-ranks-medals/docs.md) 

# Levels, Ranks & Medals

UserPoints supports two forms of user recognition: **ranks** (also called levels), which are tiers users advance through as they accumulate points, and **medals** (also called badges), which are one-off achievements awarded for specific milestones.

Both are managed from **Components → UserPoints → Level Rank**.

---

## Ranks

A rank defines a tier in your points hierarchy. Users are automatically assigned the highest rank for which they qualify based on their current point total.

### Creating a Rank or Medal

Click **New**. The **Type** field at the top of the form determines whether you are creating a rank or a medal; all other fields are the same for both.

| Field | Description |
|---|---|
| Name | The title displayed to users (e.g. "Bronze Member", "Top Contributor"). |
| Description | A short internal description of the rank or medal. Not shown to users. |
| Category | An optional Joomla content category to group this rank or medal. Useful if you manage a large number of entries. |
| Type | **Rank** or **Medal** — see below for the difference. |
| Points | The point threshold at which this rank is held or this medal is awarded. |
| Attach to a Rule | Optionally link this rank or medal to a specific rule. When set, only points earned through that rule count towards the threshold. Leave blank to count all earned points. |
| Icon | A small icon (16 × 16) shown inline next to the rank or medal name. Select from the predefined icon files installed with UserPoints. |
| Image | A larger badge image displayed on the account page. Select from the predefined image files installed with UserPoints. |

To upload your own icon or image files, use the **Upload File** panel at the bottom of the edit page. Files are stored in the component's `assets/images/awards/icons/` (icons) and `assets/images/awards/large/` (images) folders and become available in the dropdowns immediately.

Publication state (published/unpublished) is controlled from the list view using the toolbar **Publish** and **Unpublish** buttons, not from the edit form.

---

## Type: Rank vs Medal

### Rank

A rank represents the user's current level. A user holds exactly one rank at a time — the highest rank whose **Points** threshold is at or below their current balance. When the user's balance changes, their rank is re-evaluated automatically.

### Medal

A medal is a cumulative achievement. Once a user's point balance reaches the medal's **Points** threshold, they are awarded the medal permanently. They keep all medals they have ever earned, even if their balance later falls below the threshold.

---

## Rank Progression

Ranks and medals are evaluated automatically whenever a user's point balance changes. No administrator action is required. When a user crosses a threshold and advances to a new rank or earns a new medal, the **notification\_rank\_medal** plugin (if installed and published) can send them an email notification.

---

## Displaying Ranks and Medals

The user's current rank and all earned medals are shown on their frontend account page. You can also retrieve them via the UserPoints API: `UserPoints::getUserInfo($referrerid)->rank`.

---

## Email Notifications

The **Email Notification** tab on the rank/medal edit form lets you configure a notification email sent when a user achieves this rank or medal. Fields are identical to the rule notification fields:

| Field | Description |
|---|---|
| Email Notification | Enable or disable email notification for this rank or medal. |
| Subject | The email subject line. |
| Body | The email body. Supports HTML. |
| Format | Plain text or HTML. |
| BCC Admin | Send a copy to the site administrator. |

Alternatively, use the bundled **notification\_rank\_medal** plugin for generic rank/medal notifications without configuring each entry individually.

---

## The Notification Plugin

The `notification_rank_medal` plugin handles email notifications for rank changes and medal awards. Install and publish it from **Components → UserPoints → Plugins**. It sends a notification email to the user when they advance to a new rank or are awarded a new medal. No additional configuration is needed beyond publishing the plugin.

 [ ](https://manuals.remository.com/userpoints/activities) [](https://manuals.remository.com/userpoints/coupon-codes)

---

## Navigation

- Previous: [Activities](https://manuals.remository.com/userpoints/activities.md)
- Next: [Coupon Codes](https://manuals.remository.com/userpoints/coupon-codes.md)