Tooltips

Drop-in entity tooltip widget. Items resolve through GET /v2/items/{id}/tooltip — pre-formatted attribute strings, rarity tinting, gem sockets, and footer flags; spells, perks, and quests read their base record (GET /v2/{type}/{id}) and render the same parchment frame with their description text. Add one <script> tag and a data-ddb attribute on any link, and the library handles hover, fetch, position, and the card. Hover any link in the panel below to see it live.

The library posts an X-Api-Key header on every request. The key embedded in this demo is bound to darkerdb.com + its docs — register your own from the dashboard before embedding tooltips on your own site. Origin-restricted keys check the caller's Origin against the allow-list registered on the key.

Formats

Every database kind renders from one attribute. The id.<kind>. prefix on the id picks the renderer; items additionally split into an archetype and an instance mode depending on the id and modifiers you pass. Every format below is a live example — hover it.

Item — archetype

The base id — the item slug with no rarity suffix — renders the whole family at once: each primary stat as a per-rarity progression (27 / 28 / … / 36, each value tinted by its tier), plus an Up to N enchantments summary. The payload carries the family's tiers as a rarities array instead of a single rarity, and the card's rarity row reads as the span (Poor – Artifact). Hover the Arming Sword, Longsword, or War Maul archetype. Pin a tier instead — a rarity-suffixed id, or ?rarity=epic — and the progression collapses to that one tier's value (see By rarity below).

<!-- Base id (no rarity suffix) → per-rarity progression -->
<a data-ddb="id.item.arming_sword">Arming Sword</a>

Item — instance

A specific rolled drop. Any secondary[*], found_by, loot_state, quantity or other instance flag flips the card into instance mode and renders only the rolls you specified. Hover a rolled Arming Sword, a stack of five rondel daggers, or a socketed Spangenhelm.

<!-- Any instance modifier → instance mode -->
<a data-ddb="id.item.arming_sword_6001?found_by=Skullee
                     &loot_state=Identified
                     &secondary[strength]=3:Ruby">Arming Sword</a>

Spell

Class spells in the same parchment frame, carrying the ability's in-game description text below the title — the damage-type keywords colour-coded the way the game draws them. Hover Fireball, Ice Bolt, Chain Lightning, or Invisibility.

<a data-ddb="id.spell.fireball">Fireball</a>

A Sorcerer weaves two spells into a composite. The card cross-links both directions — a woven spell lists what it's Made From, a constituent lists what it Weaves Into. Hover the composite Flamefrost Spear (made from Ice Spear + Flamestrike), or Glaciate (a constituent that weaves into others).

Perk

Passive perks, same chrome, description resolved live from the codex. Hover Dual Wield, Ambush, or First Aid.

<a data-ddb="id.perk.dual_wield">Dual Wield</a>

Quest

Quest-giver text — the quest title and its briefing — rendered without an icon panel (quests carry no native icon). Hover Marks of Malice, a Goldsmith errand, or an Armourer task.

<a data-ddb="id.quest.alchemist_01">Marks of Malice</a>

Attribute

Character attributes — the primary stats and every derived modifier — each card carrying the in-game description of what the stat does, rendered without an icon panel. Hover Will, Action Speed, or Armor Rating.

<a data-ddb="id.attribute.will">Will</a>

Skill

Class skills, same parchment frame as spells, description resolved live from the codex. Hover Arcane Shield, Achilles Strike, or Backstep.

Song

Bard songs, with the buff each one grants. Hover Allegro, Aria of Alacrity, or Ballad of Courage.

Shapeshift

Druid wild-shape forms. Hover Bear, Panther, or Chicken.

Emote

Cosmetic emotes and banners. Hover Blow Kiss, Blah Blah, or Balladeer Serenade.

Class

Playable classes lead with the HUD portrait and carry their starting stats, attribute chips, and loadout counts. Hover Barbarian, Cleric, or Druid.

Monster

The creature sheet — stats, attributes, damage modifiers, and the ability list — led by the baked model render (portrait-less families fall back to a glyph). Hover Cave Troll, Lich, or Ghost King.

Merchant

The merchant's giver portrait, the services they offer (Goods / Recipes / Buybacks / Quests counts), and their greeting. Hover the Alchemist, the Weaponsmith, or the Collector.

Container

Lootable world containers — chests, ore veins, treasure piles — rendered from the prop mesh (or the named item's art). Hover an Ale cask, an Armillary Sphere, or an Anchor.

Map

Dungeon maps and their module layouts. Hover the Crypts or Goblin Caves.

Module

The dungeon rooms maps are assembled from, each with its tile art. Hover the Armory or Barracks.

Religion

The four gods, each with the stat its devotion levels scale. Hover Solaris, Zorin, or Blythar.

<!-- Every other database kind resolves the same way: the
     id.<kind>. prefix picks the renderer -->
<a data-ddb="id.skill.arcane_shield">Arcane Shield</a>
<a data-ddb="id.song.allegro">Allegro</a>
<a data-ddb="id.shape_shift.bear">Bear</a>
<a data-ddb="id.emote.blow_kiss">Blow Kiss</a>
<a data-ddb="id.class.barbarian">Barbarian</a>
<a data-ddb="id.monster.cave_troll_common">Cave Troll</a>
<a data-ddb="id.merchant.alchemist">Alchemist</a>
<a data-ddb="id.container.ale">Ale</a>
<a data-ddb="id.map.crypts_a">The Crypts</a>
<a data-ddb="id.module.armory">Armory</a>
<a data-ddb="id.religion.solaris">Solaris</a>

Localized

Append ?locale=<code> to any id and the whole card — name, stat labels and flavour text — renders in that language. The same Arming Sword in français, 日本語, or 한국어. Supported codes: en · de · es · fr · ja · ko · pt-BR · ru · zh-Hans · zh-Hant (anything else falls back to en).

<!-- ?locale=<code> renders the whole card in that language -->
<a data-ddb="id.item.arming_sword_6001?locale=fr">Arming Sword (français)</a>
<a data-ddb="id.spell.fireball?locale=ja">Fireball (日本語)</a>

Embedded (static render)

Sometimes you want the card always-on rather than on hover — the DarkerDB database pages paint item cards inline this way. Fetch the entity yourself and hand it to DDB.tooltips.render(target, entity, params); it writes the same markup into any container you give it, no hover behaviour attached.

// Fetch the entity, then paint it into a container — no hover.
const target = document.querySelector('#famine-card');
const res    = await fetch(
   'https://api.darkerdb.com/v2/items/id.item.horsemans_axe_8001/tooltip',
   { headers: { 'X-Api-Key': 'kf_live_xxxx' } }
);
const { body } = await res.json();

DDB.tooltips.render(target, body, { kind: 'item' });

The DSL

A data-ddb value is just an entity id, optionally followed by a ?key=value query string of instance modifiers:

<!-- Bare item slug — short ids without a prefix are items -->
<a data-ddb="longsword_6001">Longsword</a>

<!-- Canonical ids carry their kind in the prefix -->
<a data-ddb="id.item.longsword_6001">Longsword</a>
<a data-ddb="id.spell.fireball">Fireball</a>
<a data-ddb="id.perk.dual_wield">Dual Wield</a>
<a data-ddb="id.song.harmonic_shield">Harmonic Shield</a>
<a data-ddb="id.shape_shift.bear">Bear</a>
<a data-ddb="id.quest.alchemist_01">Marks of Malice</a>

<!-- Instance modifiers after ? — query-string style -->
<a data-ddb="id.item.templar_armor_6010?found_by=Skullee
                                       &is_tradeable=true
                                       &socket.strength=Ruby">Templar Armor</a>

The entity type is read off the id's id.<kind>. prefix — id.item.…, id.skill.…, id.spell.…, id.perk.…, id.emote.…, id.attribute.…, id.quest.… — so there's no separate type tag to remember. Bare item slugs without the id.item. prefix (longsword_6001) still resolve as items.

Triggers (and the tooltip card itself) click through to the entity's DarkerDB database page by default. Point data-ddb-link-base at your own routes to take over, or set linkBase: null in init() to disable linking entirely.

The original data-ddb-item attribute (with the longer id=…&found_by=… syntax) still works for back-compat. New embeds should use data-ddb.

Instance modifiers

By rarity

The same item shape, eight different tiers — each a rarity-suffixed id, so the card shows that tier's stat values (not the whole progression), with the title strip and rarity row colour-coded from the items endpoint's rarity field.

Hover Adventurer Tunic (poor), Rondel Dagger (common), Arming Sword (uncommon), Jester Outfit (rare), Arming Sword (epic), Arming Sword (legendary), Lavish Shirt (unique), and the artifact Famine.

<a data-ddb="id.item.adventurer_tunic_1001">Adventurer Tunic</a>  <!-- poor      -->
<a data-ddb="id.item.rondel_dagger_1001">Rondel Dagger</a>     <!-- common    -->
<a data-ddb="id.item.arming_sword_3001">Arming Sword</a>       <!-- uncommon  -->
<a data-ddb="id.item.jester_outfit_4001">Jester Outfit</a>     <!-- rare      -->
<a data-ddb="id.item.arming_sword_5001">Arming Sword</a>       <!-- epic      -->
<a data-ddb="id.item.arming_sword_6001">Arming Sword</a>       <!-- legendary -->
<a data-ddb="id.item.lavish_shirt_7001">Lavish Shirt</a>       <!-- unique    -->
<a data-ddb="id.item.horsemans_axe_8001">Famine</a>            <!-- artifact  -->

Archetype vs instance

Hovering an item with no roll overrides gives the archetype view — name, type, description, and an Up to N enchantments summary line. Adding any secondary[*], found_by, loot_state, or other instance flag auto-flips the card into instance mode and only renders the rolls you specified.

Compare the Famine template against a specific instance Skullee just rolled.

<!-- Archetype: hover the bare item template -->
<a data-ddb="id.item.horsemans_axe_8001">Famine template</a>

<!-- Instance: any non-id override flips to instance mode -->
<a data-ddb="id.item.horsemans_axe_8001?found_by=Skullee
                     &is_tradeable=true
                     &loot_state=Identified
                     &secondary[strength]=3:Ruby
                     &secondary[action_speed]=2.8:Diamond
                     &effect=When you deal damage to a target, render them unable to receive incoming healing for **20 seconds**.
                     &description=This enchanted axe is crafted by infusing the blood and essence from the third of the legendary Four Horsemen.">specific instance</a>

Gem sockets

Append :GemName to a secondary roll to socket a gem. Only Ruby, Diamond, and Emerald are mintable in the game today; the renderer maps the gem name to its in-game icon (or falls back to a coloured circle).

A Famine with all three gems; a rare Jester Outfit with a single ruby; or a epic Arming Sword with an emerald.

<!-- All three sockets filled -->
<a data-ddb="id.item.horsemans_axe_8001?loot_state=Looted
                     &secondary[strength]=3:Ruby
                     &secondary[magical_damage_bonus]=10:Emerald
                     &secondary[action_speed]=2.8:Diamond">Famine with all three gems</a>

<!-- Single ruby on a rare -->
<a data-ddb="id.item.jester_outfit_4001?loot_state=Looted
                     &secondary[strength]=2:Ruby">Jester Outfit + ruby</a>

<!-- Single emerald on an epic -->
<a data-ddb="id.item.arming_sword_5001?loot_state=Looted
                     &secondary[magical_damage_bonus]=4:Emerald">Arming Sword + emerald</a>

Whitelisted ranges

Listing a secondary attribute with no value (secondary[strength]=) renders the item's min-max range for that slot. Use this when you want to surface a particular roll's possible values without committing to a concrete number — useful for trade listings or archetype browsers.

The Jester Outfit's typical roll pool — each slot shown as its +min – max range. A slot the item can't actually roll is simply skipped.

<!-- Empty value → render the item's +min – max range for that slot -->
<a data-ddb="id.item.jester_outfit_4001?secondary[strength]=
                     &secondary[agility]=
                     &secondary[action_speed]=
                     &secondary[magical_damage_reduction]=">Jester Outfit roll pool</a>

Roll ranges

Add ?ranges=true and each rolled secondary shows the slot's possible [min ~ max] range in muted grey beside the value — so a reader sees how a roll landed against what it could have been. Only slots the item can actually roll carry a range. Hover a rolled Arming Sword with ranges.

<!-- ranges=true → each rolled secondary shows its [min ~ max] beside the value -->
<a data-ddb="id.item.arming_sword_6001?found_by=Skullee
                     &secondary[action_speed]=15:Diamond
                     &secondary[armor_penetration]=22:Ruby
                     &secondary[luck]=20:Emerald
                     &ranges=true">Arming Sword (roll ranges)</a>

Quantity + instance state

Stack-able items render a ×N badge next to the name when quantity > 1. loot_state renders in the game's teal so a glance tells the player whether the instance is looted, identified, or still being handled.

A stack of five rondel daggers looted off a kobold, a unique Lavish Shirt that's bound to the looter, or Zirkzi's Eye still being identified.

<!-- ×5 stack with a finder -->
<a data-ddb="id.item.rondel_dagger_1001?quantity=5
                     &loot_state=Looted
                     &found_by=Skullee">stack of five rondel daggers</a>

<!-- Bound to the looter -->
<a data-ddb="id.item.lavish_shirt_7001?loot_state=Identified
                     &found_by=Dildueldio
                     &is_tradeable=false">bound Lavish Shirt</a>

<!-- Mid-identification -->
<a data-ddb="id.item.crystal_ball_8001?loot_state=Handled
                     &found_by=Skullee">Zirkzi's Eye being identified</a>

Options

The data-ddb value says which entity to show; data-ddb-options says how the trigger looks and behaves. They're separate on purpose — options never ride the fetch, so dressing a link never changes what's cached.

The value is space-separated tokens. A bare key means true (usable); prefix ! to turn one off (!icon !underline); pass a value with key=value (delay=300). Unknown keys are ignored. Set it per trigger to override, or on the <script> tag for a site-wide default.

Each example below is live — hover it.

usable

A class-gated item lists its Required Class in the game's bright red — the embed has no character context, so it assumes you can't equip it. Hover the gated Arcane Garb against the same Arcane Garb with usable set — its required line drops the red gate for the neutral grey-and-tan.

underline

Triggers carry a dotted underline by default, like this one. Add !underline when the trigger is already styled as interactive and the line is gone — the hover card still fires.

icon

A small icon is injected before the name — note the art on this Arming Sword. With !icon the name stands alone (handy when your layout already shows one). The hover card keeps its own icon either way.

color

The lib tints the inline links it generates by kind. In a data-ddb-prose block (below) the names read item-slate, monster-red, spell-purple:

A Cave Troll guards the vault. Pack a Longsword and learn Fireball.

Add !color and the same block links in your own body colour — no tint leaking into your copy. The hover cards still keep their rarity-coloured names; only the inline override is dropped:

A Cave Troll guards the vault. Pack a Longsword and learn Fireball.

delay

Hover-open delay in milliseconds (default 120). Hold the cursor on this Fireball — with delay=600 it waits a beat longer than the rest before it pops.

<!-- which entity (data-ddb)  vs  how it's dressed (data-ddb-options) -->

<!-- the viewer can equip it: neutral required-class, not the red gate -->
<a data-ddb="id.item.arcane_garb_4001" data-ddb-options="usable">Arcane Garb</a>

<!-- your layout already shows an icon; the row is its own affordance -->
<div data-ddb="id.item.longsword_6001"
     data-ddb-options="!icon !underline">Longsword</div>

<!-- a slower hover-open for this one -->
<a data-ddb="id.spell.fireball" data-ddb-options="delay=300">Fireball</a>

<!-- same grammar on the script tag = a site-wide default (monochrome embed) -->
<script src=".../tooltip.min.js"
        data-ddb-key="kf_live_xxxx"
        data-ddb-options="!color"></script>

Prose

Tag a block of running text with data-ddb-prose and the library auto-links every entity name it recognises inside it — no per-link markup. The value is a comma-separated list of kinds to match (item,monster,spell,…); matching is whole-word and longest-first, so "Squire Royale" the map beats "Squire" the merchant. Each match becomes a tan, hover-tooltipped link.

A Cave Troll guards the vault past the Forgotten Castle's gate. Pack a Longsword, learn Fireball, and visit the Alchemist before you descend.

<!-- Auto-link every recognised name in a block of text -->
<p data-ddb-prose="item,monster,spell,merchant">
  A Cave Troll guards the vault past the Forgotten Castle's gate.
  Pack a Longsword, learn Fireball, and visit the Alchemist.
</p>

Install

One tag. Put your key on the data-ddb-key attribute and the script self-initializes on load; the stylesheet is fetched automatically from alongside the script, so there's no separate <link> and no init() call to write.

<script src="https://cdn.darkerdb.com/library/1.5.1/tooltip.min.js"
        data-ddb-key="kf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"></script>

<a data-ddb="barbuta_helm_3001">Barbuta</a>

That src pins a specific version. The bytes at a version path never change, so a pinned embed can't break under you. Keep it pinned unless you want auto-updates. To float to the newest release instead, swap the version segment for latest:

<script src="https://cdn.darkerdb.com/library/latest/tooltip.min.js"
        data-ddb-key="kf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"></script>

latest tracks the newest stable release and is short-cached, so a new version reaches your page within a few minutes. The trade-off: no version pin, no Subresource Integrity, and a release lands on your site with no action from you, a broken one included.

Any element with a data-ddb attribute becomes a hover trigger. The attribute's value is <id>[?key=val&…] — the entity id, plus any of the instance modifiers to render a specific roll rather than the base template. data-ddb-item with the older id=…&key=value syntax is still supported for back-compat.

Need to defer the key (fetched at runtime) or point at a custom API host? Drop the data-ddb-key attribute and call DDB.tooltips.init() yourself instead:

<script src="https://cdn.darkerdb.com/library/1.5.1/tooltip.min.js"></script>

<script>
   DDB.tooltips.init({
      key: 'kf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
   });
</script>

<a data-ddb="barbuta_helm_3001">Barbuta</a>

Script-tag knobs map to init() options: data-ddb-api-url, data-ddb-api-version, data-ddb-realm, data-ddb-link-base, data-ddb-stylesheet (to override the auto-resolved stylesheet URL), and data-ddb-options for the presentation defaults.

Presentation defaults ride data-ddb-options on the script tag, in the same grammar a trigger uses — e.g. data-ddb-options="!icon !color" for a monochrome, text-only embed. See Options for the full list. The older per-flag attributes (data-ddb-icon, data-ddb-color, data-ddb-no-icon, data-ddb-no-underline) still work as aliases.

JavaScript API

DDB.tooltips.init(options)

Initialize the library and scan the document for trigger elements. Call once at page load.

DDB.tooltips.update()

Re-scan for newly-added trigger elements. Call after a route transition or any DOM mutation that adds new data-ddb nodes.

DDB.tooltips.show(el)

Programmatically open a tooltip on the given trigger element.

DDB.tooltips.hide()

Dismiss the active tooltip.

DDB.tooltips.configure(opts)

Update runtime options (cache TTL, hover delay, etc) after init.

DDB.tooltips.render(target, entity, params)

Paint a card statically into target from an already-fetched entity payload — no hover, no fetch. params is { kind } (plus optional compact). Powers the Embedded format above.