Documentation

Everything you need to integrate mood.cards into your web app.

Getting Started

Add the mood.cards script tag to your page. You'll find your API key in your project settings.

<script src="http://mood.cards/mc.js" data-key="MC_YOUR_KEY"></script>

Place it before the closing </body> tag. The script loads asynchronously and won't block your page.

Triggering Cards

Show a feedback card programmatically using its trigger key:

MoodCards.show('checkout_flow');

You can also use the alias MoodCards.trigger() — they are identical.

Pass options as a second argument:

MoodCards.show('checkout_flow', {
  context: { orderId: 'ORD-123', total: 49.99 },
  anchor: '#checkout-btn'
});

Setting Context

Context is arbitrary JSON data attached to every submission. Use it to correlate feedback with your app state.

Inline context — passed per trigger call:

MoodCards.show('feature_x', {
  context: { userId: 42, plan: 'pro' }
});

Global context — set once, applied to all subsequent submissions:

MoodCards.setContext({ userId: 42, plan: 'pro' });

Inline context is merged with (and overrides) global context.

Setting Anchor

Anchor determines where a triggered card appears on the page. It's a CSS selector pointing to the element the card should position near.

Inline anchor — per trigger call:

MoodCards.show('checkout_flow', {
  anchor: '#checkout-btn'
});

Global anchor — set once for all triggered cards:

MoodCards.setAnchor('#main-cta');

Fallback chain: inline anchor → global anchor → card config anchor (set in dashboard) → last click position → bottom-right of viewport.

Avoid Zones

Mark areas of your page that feedback cards should not overlap. Add the .mc-avoid class to any element:

<nav class="mc-avoid">...</nav>
<div class="mc-avoid modal">...</div>

You can also configure avoid zone selectors per card in the dashboard (e.g. .modal, #sticky-header). The positioning algorithm evaluates 6 candidate positions around the anchor and avoids overlapping any zone.

Card Types

Type	Behavior
Triggered	Appears when you call `MoodCards.show()`. Shows as a contextual bubble near the anchor. Auto-dismisses after the configured timeout (default 8s).
Persistent	Always present on the page as a collapsed pill. Expands when the user clicks it. No trigger code needed.

Visibility & Suppression

Controls how often a card can appear to the same user:

Mode	Behavior
Always	Shows every time it's triggered.
Once	Shows only once per user (tracked via localStorage).
Cooldown	Shows once, then suppressed for N days.
Session	Shows once per browser session.

Debug Mode

Swap mc.js for mc_debug.js to enable debug mode:

<script src="http://mood.cards/mc_debug.js" data-key="MC_YOUR_KEY"></script>

Debug mode adds:

[MoodCards] prefixed console logs for every lifecycle event
Red dashed outlines around all .mc-avoid zones
Unminified source for easier debugging

API Reference

Method	Description
`MoodCards.show(triggerKey, options?)`	Show a triggered card. Options: `context` (object), `anchor` (CSS selector string).
`MoodCards.trigger(triggerKey, options?)`	Alias for `show()`.
`MoodCards.setContext(obj)`	Set global context merged into all submissions.
`MoodCards.setAnchor(selector)`	Set global anchor for triggered card positioning.
`MoodCards.reset()`	Clear all visibility suppression (localStorage). Cards will show again.
`MoodCards.destroy()`	Remove all mood.cards DOM elements and event listeners.

Utilities

`reset()`

Clears all stored visibility state from localStorage. Useful during development to re-show "once" or "cooldown" cards:

MoodCards.reset();

`destroy()`

Fully tears down the mood.cards instance — removes all injected DOM elements, clears event listeners, and stops any pending timers:

MoodCards.destroy();

Useful when navigating away in a SPA or cleaning up in tests.

AI-Friendly Docs

Building with an AI coding assistant? Point it to our machine-readable docs:

/llms.txt — quick API summary
/llms-full.txt — complete integration guide