Waitlist
Leaderboard Embed
The leaderboard embed lets you display your top referrers on any website — separately from your sign-up form. It's ideal for landing pages, blog posts, community sites, or anywhere you want to showcase engagement and drive competition around your referral program.
Requirements
The leaderboard embed is available on paid plans, starting from the Launch plan. If the owner of a waitlist is on the Free plan, the embed will display an "upgrade required" message instead of the leaderboard.
Your waitlist must have at least one subscriber with referrals (or points, depending on your chosen metric) for the leaderboard to show any data. Otherwise, visitors will see an empty state.
Embedding Your Leaderboard
There are two simple steps to embed your leaderboard on any website.
1. Add Script to Head
First, add the Waitlister leaderboard embed script to your website's <head> section.
<script src="https://waitlister.me/js/embed-leaderboard.js" defer></script>
The script is the same for all leaderboards.
2. Add Leaderboard Container
Next, add a div container with your unique waitlist key where you want the leaderboard to appear.
<div
class="waitlister-leaderboard"
data-waitlist-key="YOUR-WAITLIST-KEY"
></div>
You can find your waitlist key by navigating to the "Overview" page in your waitlist dashboard.
3. Your Leaderboard is Ready
That's it. The leaderboard will automatically render, fetch the current top referrers, and resize to fit its content.
Customization
Unlike the form, there is no dashboard editor for the leaderboard embed. Instead, you customize it entirely through data-* attributes on the container div. This keeps the embed lightweight and lets you iterate on styling directly in your site's code.
Basic Example
<div
class="waitlister-leaderboard"
data-waitlist-key="YOUR-WAITLIST-KEY"
data-positions="20"
data-title="Top Referrers"
data-accent-color="#ff5733"
></div>
Dark Theme Example
<div
class="waitlister-leaderboard"
data-waitlist-key="YOUR-WAITLIST-KEY"
data-positions="10"
data-title="Leaderboard"
data-bg-color="#0f172a"
data-text-color="#e5e7eb"
data-title-color="#ffffff"
data-border-color="#1e293b"
data-border-radius="16"
data-accent-color="#3b82f6"
data-badge-shape="rounded"
></div>
Minimal Example
<div
class="waitlister-leaderboard"
data-waitlist-key="YOUR-WAITLIST-KEY"
data-positions="5"
data-show-title="false"
data-padding="8"
data-max-width="360"
data-border-width="0"
></div>
Customization Reference
All attributes are optional. If omitted, the default value is used.
Data
| Attribute | Type | Default | Description |
|---|---|---|---|
data-positions | number (1-50) | 10 | Number of entries to display |
data-metric | referrals or points | referrals | Which value to show next to each entry |
Layout
| Attribute | Type | Default | Description |
|---|---|---|---|
data-alignment | left, center, or right | center | Horizontal alignment of the leaderboard and title |
data-padding | number (0-64) | 16 | Inner padding in pixels |
data-max-width | number (240-1200) | 480 | Maximum width of the leaderboard in pixels |
Title
| Attribute | Type | Default | Description |
|---|---|---|---|
data-show-title | true or false | true | Whether to display the title |
data-title | string | Leaderboard | Title text |
data-title-color | color (hex) | #111111 | Title text color |
data-title-size | number (10-48) | 20 | Title font size in pixels |
data-title-weight | number (100-900) | 600 | Title font weight |
data-title-font-family | string | font-poppins | Title font family |
Body
| Attribute | Type | Default | Description |
|---|---|---|---|
data-text-color | color (hex) | #333333 | Body text color |
data-body-font-family | string | font-open-sans | Body font family |
data-body-size | number (10-24) | 14 | Body font size in pixels |
Container
| Attribute | Type | Default | Description |
|---|---|---|---|
data-bg-color | color (hex) | #ffffff | Background color |
data-border-color | color (hex) | #e5e7eb | Border color |
data-border-width | number (0-8) | 1 | Border width in pixels |
data-border-radius | number (0-32) | 8 | Border radius in pixels |
Rows
| Attribute | Type | Default | Description |
|---|---|---|---|
data-row-alt-bg | true or false | false | Enable alternating row background colors |
data-row-bg-color | color (hex) | transparent | Background color for standard rows |
data-row-alt-color | color (hex) | transparent | Background color for alternating rows (when enabled) |
Position Badge
| Attribute | Type | Default | Description |
|---|---|---|---|
data-accent-color | color (hex) | #3b82f6 | Background color of the position badge |
data-badge-shape | circle, square, or rounded | circle | Shape of the position badge |
Labels
Override the default column headers. Useful for custom wording or languages not yet supported.
| Attribute | Type | Default | Description |
|---|---|---|---|
data-position-label | string | # | Header text for the position column |
data-email-label | string | Email | Header text for the email column |
data-referrals-label | string | Referrals | Header text for the referrals/points column |
data-empty-text | string | No subscribers yet | Text shown when there are no entries |
Behavior
| Attribute | Type | Default | Description |
|---|---|---|---|
data-refresh-interval | number (0 or 60-3600) | 300 | Auto-refresh interval in seconds. Set to 0 to disable. Minimum 60 seconds |
data-language | string | en | Language code for default labels (matches the languages supported in your form) |
Multiple Leaderboards on One Page
You can embed multiple leaderboards on the same page, including from different waitlists. Each div is independent and can have its own customization.
<div
class="waitlister-leaderboard"
data-waitlist-key="WAITLIST-KEY-A"
data-title="Top Referrers"
></div>
<div
class="waitlister-leaderboard"
data-waitlist-key="WAITLIST-KEY-B"
data-title="Most Points"
data-metric="points"
></div>
Privacy
Subscriber emails are automatically scrambled before being displayed. For example, [email protected] appears as j*****@e*****.com. No personal information is exposed to visitors.
Auto-Resize
The leaderboard automatically calculates its height based on the number of entries and your customization. If you change data-positions or any styling later, the iframe resizes itself to fit the new content. You do not need to specify a fixed height.
Troubleshooting
The leaderboard shows an empty state: Your waitlist has no subscribers with referrals yet. Once someone signs up through a referral link, they'll appear on the leaderboard.
I see "Leaderboard embed unavailable": The waitlist owner is on the Free plan. Upgrading to Launch or higher will enable the embed.
The leaderboard isn't appearing: Check that the embed script is in your <head> section and that your container div has both the waitlister-leaderboard class and a valid data-waitlist-key attribute.
Colors look off on a dark background: Make sure to customize data-text-color and data-title-color alongside data-bg-color to keep text readable. If you use data-row-alt-bg="true", also set data-row-alt-color to a color that contrasts with your text.
Help and Support
Need assistance with your leaderboard embed? We're here to help.
- Contact us via the public contact form
- Access the "Help" page in your account dashboard