Mapping Page Data: Button placement and behaviour

This guide is part of Mapping Page Data into Toggl.

Mapping decides what gets recorded; these options decide where the button appears, when, and how it behaves. If you build with the Claude skill it handles most of this for you — this page is for when you need to correct it.

Where the button goes

Option	What it does
`anchor`	Required. The CSS selector the button attaches to.
`append`	Where relative to the anchor: `last` and `first` go inside it, `after` and `before` beside it. Omit it and the button lands just before the anchor, as a sibling.
`multiple`	`false` (default) mounts one button on the page. `true` mounts one per matching anchor — a board or a list.
`target`	Accepted by the editor but not read by the current extension. Anchors are always searched across the whole document.
`wrapper`	An HTML snippet cloned to hold the button, e.g. a `div` with inline flex styling. Use it to make the button sit correctly in the host layout.
`className`	Classes applied to that wrapper.
`initialClassName`	Accepted by the editor but not read by the current extension. Use `className`.
`container`	Where the button's popover is rendered, for items that open inside a modal or overlay — Jira points it at the issue-modal blanket so the popover is not trapped under it. The least-used option; copy an existing integration rather than deriving it.

🧨 A malformed anchor selector is handed straight to the browser during mount, uncaught. It throws and unmounts every button in the integration, not just that one. This is why the editor validates CSS selectors before it lets you save.

When the button appears

"matches": ["^/browse/", "^/projects/[^/]+/issues"]

A list of regexes tested against the page's path (not the full URL). If any matches, the button mounts; if none do, it does not. Omit it entirely and the button mounts wherever the anchor is found.

Use it when one site has several page types and the anchor selector is not specific enough to tell them apart on its own.

How the button behaves

Option	What it does
`autoTrack`	Starts tracking automatically when the user lands on the item, without a click. Powerful and intrusive in equal measure — the user can turn it off per integration from the Integrations list.
`quickLog`	Adds the duration menu beside the button — 15min, 30min, 1h, 2h — for logging time already spent instead of starting a timer.
`subscribe`	An element selector to watch. When it changes, the values are resolved again. Essential on single-page apps where navigating between items swaps the content without reloading the page.
`variant`	`minimal` or `default`. Minimal is the compact icon-only form used inside dense chrome like a breadcrumb.
`iconSize`	Pixel size of the icon. Match it to the host UI — 16 in a toolbar, 20 in a page header.

🔁 subscribe is the option people forget. Without it, a Jira user who clicks from one issue to the next gets a button still advertising the previous issue's title — and starts a timer against the wrong task. Point it at whatever element carries the item's title.

How it looks

Option	What it does
`cssContent`	CSS injected alongside the button. The usual reason is beating a host page's click overlay — cards that are "click anywhere to open" will swallow the button unless it gets its own stacking context.
`cssFile`	The same thing from a file rather than inline.
`themeDetector`	`colorElement` names an element whose colour decides light or dark; `watchElement` names one to watch for theme changes. Without it the button can read as light-on-light in a dark-themed host.

The click-overlay fix, from the GitLab boards example:

"cssContent": "[data-toggl-button-wrapper=\"card-button\"]{position:relative;isolation:isolate;z-index:1;}"

⚠️ Visible is not the same as clickable. On boards and card layouts the button can render perfectly and still be unclickable, because a stretched "open this card" overlay sits on top of it. The fix is a separate stacking context (isolation: isolate), not a bigger z-index. Always click the button before declaring it done.

One definition, several surfaces

A list view and a detail view are different buttons in the same definition, each with its own anchor, multiple and scoping. Do not try to make one button serve both — the anchors and the scoping rules genuinely differ.

GitHub ships exactly this shape: an issues-button and a separate pr-button, with different anchors and different resolvers.