Skip to Content
v1.39.1 · shipped More settings on the script tag · Script tag typos no longer slip through Read the changelog →
SDK referenceTheming the widget

Theming the bug widget

The widget already uses your page’s font and follows light or dark mode, so most apps need nothing here. When you want it to look like yours, start with the easiest way that fits how you built the app.

Three easy ways

1. Script tag (Lovable, Bolt, plain HTML)

Add attributes to the tag you pasted:

index.html
<script async src="https://cdn.jsdelivr.net/npm/@mushi-mushi/web@1/dist/mushi.loader.global.js" data-project="YOUR_PROJECT_ID" data-key="YOUR_API_KEY" data-accent="#7c3aed" data-theme="auto" data-position="bottom-left" data-locale="ja" data-hide-on-routes="/admin/*, /checkout" ></script>
AttributeWhat it doesAccepted values
data-accentColour of the Send button and the launcher’s underline#rgb, #rrggbb, rgb(), hsl(), oklch()
data-accent-textText colour on the accent (picked for you when left out)the same, plus black or white
data-themeLight or dark widgetauto (default), light, dark, inherit (read your page’s class or data-theme)
data-positionCorner for the launcherbottom-right (default), bottom-left, top-right, top-left
data-localeWidget languageauto (browser language, default), en, ja, th, es, zh; region tags such as ja-JP work
data-hide-on-routesPages where the launcher stays hiddencomma-separated route rules
data-triggerLauncher styleauto, banner, edge-tab, attach, manual, hidden
data-trigger-textLauncher labelany text
data-banner-variantBanner look, with data-trigger="banner"subtle, brand, neon
data-banner-positionBanner edgetop, bottom

A value the widget does not accept is skipped, and the browser console shows one warning naming the attribute and the values it takes, for example [mushi] Ignored data-theme="purple". Use one of: auto, light, dark, inherit. A typo never breaks your page or stops the widget.

2. In code

import { Mushi } from 'mushi-mushi' Mushi.init({ projectId: 'YOUR_PROJECT_ID', apiKey: 'YOUR_API_KEY', widget: { accent: '#7c3aed', theme: 'auto', position: 'bottom-left', locale: 'ja', hideOnRoutes: ['/admin/*', '/checkout'], }, })

React, Vue, Svelte and Angular take the same widget object through their provider or plugin.

3. In the console

Open your app in the console, then Connect → Bug capture SDK. Accent colour, position, theme, launcher style, launcher label and the banner look can change there without a redeploy (runtime config). For a colour, Mushi picks black or white text with at least 3:1 contrast. The same settings are in your editor: the MCP tool set_widget_settings, or mushi widget set --accent '#3b5bdb'. Language and hidden pages are set in the tag or in code.

If your app’s code (or a data-* attribute) sets one of these, your code’s value wins and the console fills only what the code left out (ADR 0068 ). The console’s install snippets leave them out unless you tick Lock these settings in my code.

What can be set where

SettingScript tagCode (widget.*)ConsoleCSS token
Accent colourdata-accentaccentyes--mushi-accent
Text on the accentdata-accent-textaccentTextpicked with the colour--mushi-accent-fg
Light / darkdata-themethemeyes
Cornerdata-positionpositionyes
Languagedata-localelocale
Hidden pagesdata-hide-on-routeshideOnRoutes
Launcher style and labeldata-trigger, data-trigger-texttrigger, triggerTextyes
Banner lookdata-banner-variant, data-banner-positionbannerConfigyes
Fonts, surfaces, corners, shadowthe tokens below

CSS tokens

For finer control, set any of these 13 tokens in your own CSS, on :root or on #mushi-mushi-widget. CSS always wins over widget.accent and the other options. Values left unset follow your page: Canvas and CanvasText are the browser’s own page colours, so they flip with light and dark mode.

#mushi-mushi-widget { --mushi-accent: #7c3aed; --mushi-font: 'Inter', sans-serif; --mushi-radius: 8px; }
TokenControlsLight defaultDark default
--mushi-fontFont familyyour page’s fontyour page’s font
--mushi-font-sizeBase text size14px14px
--mushi-bgPanel and launcher backgroundCanvas (white)Canvas (near black)
--mushi-fgMain textCanvasText (black)CanvasText (white)
--mushi-mutedHints and secondary texttext at 64%text at 64%
--mushi-surfaceInputs and cards inside the panelbackground mixed with 6% textbackground mixed with 6% text
--mushi-borderHairlines and outlinestext at 16%text at 16%
--mushi-accentSend button, launcher underline, focus ringswidget.accent, else your page’s accent-color or theme-color (when it reads at 3:1), else the text coloursame
--mushi-accent-fgText on the accentblack or white, whichever reads bettersame
--mushi-success”Sent” states#2D7A55#3A9E6E
--mushi-errorErrors#B83232#E05555
--mushi-radiusPanel corner radius12px12px
--mushi-shadowPanel shadow0 12px 40px rgb(0 0 0 / .18)same

These 13 names are a public contract: a test in the SDK fails if one is renamed or removed.

Contrast rule

Text on the accent must reach at least 3:1 contrast, so the Send button stays readable. The widget never changes your accent colour itself. It only checks the text on top of it:

  • No accentText: the widget picks black or white, whichever reads better.
  • Your accentText, data-accent-text or --mushi-accent-fg reaches 3:1: it is kept.
  • It falls under 3:1: the widget uses black or white instead and records a warning. Read it with Mushi.diagnose():
const report = await Mushi.diagnose() console.log(report.warnings) // ['Accent text #ffffff is 1.2:1 on #ffeb3b (under 3:1); using black.']

With debug: true (or data-debug="true") the same warning is printed to the browser console.

An accent taken from your page (accent-color or <meta name="theme-color">) is only used when it reaches 3:1 against the panel background; otherwise the widget keeps the text colour as its accent.

Route rules

hideOnRoutes hides the launcher on matching pages. Each entry is checked against the page path (no domain, no query string):

RuleHidesDoes not hide
/checkout/checkout, /checkout/done, /shop/checkout/cart
/admin/*/admin/users, /admin/users//admin, /admin/users/5
/blog/**/blog, /blog/2026/my-post/blogroll
/docs/*/edit/docs/intro/edit/docs/a/b/edit
  • An entry without * matches anywhere in the path, the way hideOnRoutes always worked, so existing setups keep their behaviour.
  • * matches one path segment; ** matches any number of them.
  • A trailing /** also matches the path itself.
  • A trailing / on the page path is ignored.

Your own button

Hide the launcher and open the widget from a button in your app:

const mushi = Mushi.init({ projectId: 'YOUR_PROJECT_ID', apiKey: 'YOUR_API_KEY', widget: { trigger: 'manual' }, }) document.querySelector('#report-bug')?.addEventListener('click', () => mushi.open())

Mushi.getInstance()?.open() does the same from anywhere else in your app. To bind the widget to an existing element without writing a click handler, use widget: { trigger: 'attach', attachToSelector: '#report-bug' }. The script tag gives your page no JavaScript handle, so a button of your own needs one of these code installs. More launcher styles: trigger modes.

Last updated on