> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://help.tako.id/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # How to Create Custom Overlay Want your *stream* to look cooler with your own custom overlay? A custom overlay is like a blank canvas you build with HTML. Make special messages, fun animations, or branding that makes people instantly remember you! ## What Overlay Types Can Be Customized? 1. **Alert** (Doesn't include media like Voice Note or GIF) 2. **Media Share** (Only the message part is customizable; media/video and the progress bar aren't) 3. **Leaderboard** 4. **Timer** (Re-renders every second **only if** your code uses `{{timeLeft}}` or `{{timeLeftMs}}`. Use `{{timerEndAt}}` alone and run your own countdown in ` ``` 💡 `{{timestamp}}` and `{{showTimestamp}}` work on both Alert and Media Share. `{{showTimestamp}}` follows whichever overlay is currently showing: if the gift is a mediashare, it reads the Media Share toggle, not Alert's. --- ### 2. Leaderboard | Variable Name | Example Value | Description | | ---- | | `{{title}}` | `Top Donors This Month` | Leaderboard title from settings. | | `{{rankings}}` | `[{"name":"BudiGaming","picture":"https://example.com/profile.jpg","badges":"VIP,TopDonator","amount":15000,"formattedAmount":"Rp15.000"}, ...]` | Ranking list (JSON): name, picture, badges (names only, comma-separated; **no icon URL**), donation amount, formatted amount. | **Example Code:** ```html

``` --- ### 3. Milestone | Variable Name | Example Value | Description | | ---- | | `{{title}}` | `Around the Archipelago` | Milestone title from settings. | | `{{currentAmount}}` | `75000` | Total raised across all steps (raw number). | | `{{formattedCurrentAmount}}` | `IDR 75.000` | Total raised, formatted. | | `{{targetAmount}}` | `100000` | Total target across all steps (raw number). | | `{{formattedTargetAmount}}` | `IDR 100.000` | Total target, formatted. | | `{{overallPercentage}}` | `75` | Overall progress percentage (0-100, can exceed 100 if overshot). | | `{{stepProgress}}` | `25000` | Progress within the currently active step only (raw number). | | `{{formattedStepProgress}}` | `IDR 25.000` | Active step's progress, formatted. | | `{{stepTarget}}` | `50000` | Currently active step's target (raw number). | | `{{formattedStepTarget}}` | `IDR 50.000` | Active step's target, formatted. | | `{{percentage}}` | `50` | Active step's progress percentage (0-100). | | `{{stepIndex}}` | `2` | Active step's order number (starts at 1). | | `{{stepCount}}` | `4` | Total number of steps. | | `{{stepTitle}}` | `Step 2: Bali` | Active step's title (empty if not set). | | `{{steps}}` / `{{milestoneSteps}}` | `[{"title":"Step 1","target":25000,"currentAmount":25000,"percentage":100,"isActive":false}, ...]` | List of all steps (JSON), each item has `formattedTarget`/`formattedCurrentAmount`. | **Example Code:** ```html

Step {{stepIndex}} / {{stepCount}}

``` --- ### 4. Polling | Variable Name | Example Value | Description | | ---- | | `{{title}}` | `Pick the Next Game!` | Poll title from settings. | | `{{pollingOptions}}` | `[{"id":1,"name":"Game A","totalAmount":5000,"formattedTotalAmount":"Rp5.000"}, ...]` | Poll options list (JSON): ID, name, donation amount, formatted amount. | | `{{startAt}}` | `2025-07-08` | Poll start date. | | `{{startTime}}` | `09:30` | Poll start time. | | `{{endAt}}` | `2025-07-08` | Poll end date. | | `{{endTime}}` | `12:30` | Poll end time. | **Example Code:** ```html

{{startAt}} {{startTime}} — {{endAt}} {{endTime}}

``` --- ### 5. Running Text | Variable Name | Example Value | Description | | ---- | | `{{texts}}` | `[{"title":"Welcome!","backgroundColor":"#333","textColor":"#FFF"}, ...]` | Extra text list (JSON): title, background color, text color. | | `{{gifts}}` | `[{"gifterName":"BudiGaming","amount":15000,"formattedAmount":"Rp15.000"}, ...]` | Donation list (JSON): donor name, amount, formatted amount. | **Example Code:** ```html

``` Appending `buildItems()` twice makes the scroll seamless (two copies of the content sit side by side, and `translateX(-50%)` stops exactly when the second copy reaches the first copy's position). This overlay has no 250ms progress-tick like Song Share, so the CSS animation loop is safe to run continuously without restarting. --- ### 6. Soundboard | Variable Name | Example Value | Description | | ---- | | `{{amount}}` | `15000` | Donation amount (raw number). | | `{{formattedAmount}}` | `Rp15.000` | Formatted donation amount. | | `{{soundName}}` | `Explosion` | Name of the chosen sound effect. | | `{{gifterName}}` | `BudiGaming` | Donor's name. | | `{{gifterPicture}}` | https://example.com/profile.jpg | Donor's profile picture URL. | | `{{gifterBadges}}` | `VIP,TopDonator` | Donor's badge names, comma-separated; **no icon URL** from the system. | | `{{isGifterVerified}}` | `true` or `false` | Donor's verification status (`true` if verified). | **Example Code:** ```html

🔊

🔈 {{soundName}}

``` --- ### 7. Timer | Variable Name | Example Value | Description | | ---- | | `{{title}}` | `Event Starting!` | Timer title from settings. | | `{{timeLeft}}` | `05:30` | Time left in `MM:SS` format (or `00:00` when expired). **Changes every second**, which causes the overlay to re-render every second. | | `{{timeLeftMs}}` | `330000` | Time left in milliseconds (raw number). **Changes every second** too. | | `{{timerEndAt}}` | `1757568540000` | When the timer expires, as an epoch millisecond timestamp (`0` = timer inactive / not running). This value **only changes when time is added/removed/reset**, so if your code uses only this (without `{{timeLeft}}`/`{{timeLeftMs}}`), the overlay renders once and you run your own countdown in JS, so your animation never resets every second. | | `{{timerAddedMs}}` | `60000` | The most recent time change, in milliseconds. Negative = time removed. `0` if there's been no change since the overlay loaded. | | `{{timerAddedSeconds}}` | `60` | Same as above, in seconds. | | `{{timerAdded}}` | `+01:00` | Same, fully formatted with a plus/minus sign. Empty if there's been no change yet. | | `{{isEnabled}}` | `true` or `false` | Timer status (`true` if active). | | `{{options}}` | `[{"durationAdded":300,"minimumGiftAmount":10000}, ...]` | Timer options list (JSON): `durationAdded` = time added, in **seconds**, `minimumGiftAmount` = minimum donation amount to earn that addition. Example alongside: a Rp10,000 donation adds 300 seconds (5 minutes). | 💡 How time gets added: viewer donates → Tako computes it against the rules in "Time Addition Rules" → `{{timerEndAt}}` moves back by that amount → `{{timerAddedSeconds}}` & `{{timerAdded}}` fill in with the amount just added. So if the rule is Rp10,000 = 1 minute and someone donates Rp10,000, `{{timerAdded}}` becomes `+01:00`, perfect for a "time added!" animation. **Example Code:** ```html

{{title}} Active

--:--

``` This example never touches `{{timeLeft}}` at all, so the overlay renders exactly once: a `setInterval` inside the iframe handles the countdown itself. Your animations/transitions stay safe from resetting every second. If you'd rather keep it simple and don't mind the overlay re-rendering every second, just swap `.countdown`'s content for `{{timeLeft}}` and drop the countdown script. --- ### 8. VIP Queue | Variable Name | Example Value | Description | | ---- | | `{{title}}` | `VIP Queue` | Title from settings. | | `{{totalEntries}}` | `7` | Total number of people in the queue. | | `{{hiddenCount}}` | `2` | Number of entries not shown because they exceed the display limit (`displayedQueueLimit` in settings). | | `{{showFields}}` | `"true"` or `"false"` (string) | Whether custom fields (e.g. address, note) are shown. | | `{{visibleEntries}}` | `[{"index":1,"id":"1","name":"BudiGaming","picture":"https://example.com/profile.jpg","badges":"VIP,TopDonator","badgeItems":[{"url":"https://tako.id/images/badges/verified-creator.png","title":"Verified Creator"}],"isVerified":true,"amount":15000,"formattedAmount":"Rp15.000","fields":[{"label":"Address","value":"123 Merdeka St"}]}, ...]` | Queue list **already** cut down to the display limit (JSON), used for rendering. Each entry has `badgeItems`: an array of real badges (icon + title), used to render badges as **images**, not just text. | | `{{entries}}` / `{{queue}}` | same structure as `visibleEntries` | List of **all** entries (JSON), not cut down to the limit. | | `{{fields}}` | `[{"label":"Address","value":"123 Merdeka St"}, ...]` | All custom fields from every entry, flattened into one array (JSON). | **Example Code:** ```html

``` --- ### 9. Song Share | Variable Name | Example Value | Description | | ---- | | `{{title}}` / `{{songTitle}}` | `Song Title` | Title of the song currently playing. | | `{{songArtist}}` | `Artist Name` | Artist of the song currently playing. | | `{{songCoverArtUrl}}` | https://example.com/cover.jpg | Cover art URL of the song currently playing. | | `{{requesterName}}` | `BudiGaming` | Name of the person who requested the song. | | `{{requesterPicture}}` | https://example.com/profile.jpg | Requester's profile picture URL. | | `{{requesterBadges}}` | `VIP,TopDonator` | Requester's badge names (names only, comma-separated). **No icon URL** from the system for this "Now Playing" row. Fill in `BADGE_ICON_URLS` manually in the script if you want it shown as an image; the code below already has the 6 official Tako system badges filled in, see the table under Alert (§1). | | `{{isRequesterVerified}}` | `true` or `false` | Requester's verification status. | | `{{duration}}` | `215` (seconds) | Song duration (raw number). | | `{{formattedDuration}}` | `03:35` | Formatted song duration. | | `{{elapsed}}` | `42` (seconds) | Elapsed playback time (raw number). | | `{{formattedElapsed}}` | `00:42` | Formatted elapsed playback time. | | `{{progressPercent}}` | `19` | Song progress percentage (0-100), use it to build your own progress bar. | | `{{isPlaying}}` | `true` or `false` | Whether the song is currently playing. | | `{{isPaused}}` | `true` or `false` | Whether the song is currently paused. | | `{{isInGap}}` | `true` or `false` | Whether it's currently in a gap between songs. | | `{{gapRemaining}}` | `3` (seconds) | Time left in the gap between songs. | | `{{gapText}}` | `Next Song At 00:03` | Status text for the gap between songs. | | `{{error}}` | `Song failed to play` | Error message if any, empty if none. | | `{{nowPlaying}}` | `{"id":"1","title":"Song Title","artist":"Artist Name","coverArtUrl":"...","duration":215,"formattedDuration":"03:35","sender":{"name":"BudiGaming"},...}` | Object (JSON) of the song currently playing, `null` if none. | | `{{queue}}` / `{{queues}}` | `[{"id":"2","title":"Queued Song","artist":"Another Artist","duration":180,"senderName":"Another Supporter","senderBadges":"VIP,TopDonator","senderBadgeItems":[{"url":"https://tako.id/images/badges/verified-creator.png","title":"Verified Creator"}],...}, ...]` | List of upcoming songs in the queue (JSON). Each item has `senderBadgeItems`: an array of real badges (icon + title) for that song's requester, which genuinely can be rendered as an **image**. | **Example Code:** ```html

Now Playing

♪

{{formattedElapsed}} / {{formattedDuration}}

Up Next

``` --- ## Additional Info You Might See * **"⚠ This is a test message"**: Shows when the overlay is being tested or previewed. * **"⛔ Sent by Admin"**: Shows when a gift is sent by Tako's team/admin. --- ## How to Implement/Build a Custom Overlay 1. **Log into your Creator Dashboard** 2. **Find the "Overlays" menu on the left** 3. **Pick an overlay** (e.g. Alert) 4. **Under "Theme", switch to "Custom HTML"**. 5. Copy-paste the code you built into the textarea that appears. 6. **Check the preview** at the top. ${youtube}[How to Make Custom Overlay in Tako!](8PEOMWGBN4w)