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:
<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>| Attribute | What it does | Accepted values |
|---|---|---|
data-accent | Colour of the Send button and the launcher’s underline | #rgb, #rrggbb, rgb(), hsl(), oklch() |
data-accent-text | Text colour on the accent (picked for you when left out) | the same, plus black or white |
data-theme | Light or dark widget | auto (default), light, dark, inherit (read your page’s class or data-theme) |
data-position | Corner for the launcher | bottom-right (default), bottom-left, top-right, top-left |
data-locale | Widget language | auto (browser language, default), en, ja, th, es, zh; region tags such as ja-JP work |
data-hide-on-routes | Pages where the launcher stays hidden | comma-separated route rules |
data-trigger | Launcher style | auto, banner, edge-tab, attach, manual, hidden |
data-trigger-text | Launcher label | any text |
data-banner-variant | Banner look, with data-trigger="banner" | subtle, brand, neon |
data-banner-position | Banner edge | top, 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
| Setting | Script tag | Code (widget.*) | Console | CSS token |
|---|---|---|---|---|
| Accent colour | data-accent | accent | yes | --mushi-accent |
| Text on the accent | data-accent-text | accentText | picked with the colour | --mushi-accent-fg |
| Light / dark | data-theme | theme | yes | |
| Corner | data-position | position | yes | |
| Language | data-locale | locale | ||
| Hidden pages | data-hide-on-routes | hideOnRoutes | ||
| Launcher style and label | data-trigger, data-trigger-text | trigger, triggerText | yes | |
| Banner look | data-banner-variant, data-banner-position | bannerConfig | yes | |
| Fonts, surfaces, corners, shadow | the 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;
}| Token | Controls | Light default | Dark default |
|---|---|---|---|
--mushi-font | Font family | your page’s font | your page’s font |
--mushi-font-size | Base text size | 14px | 14px |
--mushi-bg | Panel and launcher background | Canvas (white) | Canvas (near black) |
--mushi-fg | Main text | CanvasText (black) | CanvasText (white) |
--mushi-muted | Hints and secondary text | text at 64% | text at 64% |
--mushi-surface | Inputs and cards inside the panel | background mixed with 6% text | background mixed with 6% text |
--mushi-border | Hairlines and outlines | text at 16% | text at 16% |
--mushi-accent | Send button, launcher underline, focus rings | widget.accent, else your page’s accent-color or theme-color (when it reads at 3:1), else the text colour | same |
--mushi-accent-fg | Text on the accent | black or white, whichever reads better | same |
--mushi-success | ”Sent” states | #2D7A55 | #3A9E6E |
--mushi-error | Errors | #B83232 | #E05555 |
--mushi-radius | Panel corner radius | 12px | 12px |
--mushi-shadow | Panel shadow | 0 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-textor--mushi-accent-fgreaches 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):
| Rule | Hides | Does 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 wayhideOnRoutesalways 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.