Documentation

You're about 30 seconds from collecting feedback. Here's everything you need.

Getting Started

Drop the script tag into your page. Grab your API key from project settings, and you're live.

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

Place it before the closing </body> tag. It loads async, 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. Can also be expanded programmatically via `MoodCards.show('trigger_key')`.

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="https://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