Mount options & appearance
Every mount option, theming tokens, secure fields and locales.
| Option | Type | Default | Notes |
|---|---|---|---|
publishableKey | string | data-key | Public, origin-restricted. |
componentId | string | — | Identifies the configured component (layout, theme, copy, reward). |
intent | payment | buy_now | subscription | connect | payment | Drives copy, gating and the intent record. |
mode | inline | button | inline | Inline embed or a single button. |
completion | component | merchant | component | Inline mode: who owns the action button. |
presentation | modal | popup | redirect | modal | Button mode only: how the experience opens. |
authPresentation | modal | popup | redirect | modal | Inline mode: how bank authentication opens. |
amount | integer | — | Minor units. Required for payment intents. |
currency | ISO 4217 | USD | Formatting and eligible institutions. |
orderId | string | — | Echoed back on success. |
merchantCustomerRef | string | null | Set when the payer is logged in at the merchant. Unlocks merchant-scoped saved accounts. |
payerHint | string | null | Email/phone used to look up DRUO network accounts for logged-out payers. |
allowSaveAccount | boolean | true | Shows "save this account for future purchases here". |
saveAccountDefault | boolean | false | Pre-checks that box. |
payloadHash | string | null | HMAC of the payload when tamper protection is ON. |
returnUrl | string | current URL | Redirect presentation only. |
buttonLabel | string | auto | Button mode label override. |
locale | BCP-47 | device locale | Any locale is served; missing strings are translated on first load and cached. |
appearance | object | component config | Appearance API — theme preset, variables, rules. Direct equivalent of Stripe's appearance. |
theme | object | component config | Legacy shorthand object (accent, radius, fontFamily, …). Still supported; appearance wins. |
secureFields | boolean | false | Renders the institution fields inside a DRUO-hosted iframe; merchant JS never touches the values. |
authMethods | string[] | backend-chosen | Optional preference hint; the backend still decides what this account allows. |
Appearance API
DRUO's appearance option mirrors Stripe Elements' appearance API one-for-one: a base theme preset, a set of variables (design tokens), and rules (per-element CSS). Everything is scoped to the mounted instance, so two components on the same page can look completely different.
Druo.mount("#druo", {
publishableKey: "pk_test_…",
appearance: {
theme: "flat", // default | flat | minimal | night
variables: {
colorPrimary: "#0f9d76",
colorBackground: "#ffffff",
colorText: "#101828",
colorDanger: "#d92d20",
fontFamily: "Inter, system-ui, sans-serif",
borderRadius: "14px",
},
rules: {
".Input": { borderWidth: "2px", padding: "13px 14px" },
".Input--invalid": { boxShadow: "0 0 0 3px rgba(217,45,32,.12)" },
".Label": { textTransform: "uppercase", letterSpacing: ".04em" },
".Button": { borderRadius: "999px", fontWeight: "700" },
".Account--selected": { boxShadow: "0 0 0 3px rgba(15,157,118,.12)" },
},
},
});Presets (appearance.theme)
| Preset | Look |
|---|---|
default | DRUO's shipped light theme. |
flat | Borderless, tinted surfaces, tighter radius. |
minimal | White surfaces, hairline borders, 6px radius. |
night | Dark surfaces with light text. |
Variables (appearance.variables) — friendly names mapped to CSS custom properties:
| Variable | CSS variable | Applies to |
|---|---|---|
colorPrimary | --druo | Buttons, selected account, focus ring, links. |
colorPrimaryText | --druo-fg | Text on the primary button. |
colorBackground | --druo-bg | Card, inputs, dialog background. |
colorSurface | --druo-surface | Subtle fills, hovers, skeletons. |
colorText | --druo-text | Primary text. |
colorTextSecondary | --druo-muted | Helper, trust and label text. |
colorDanger | --druo-danger | Errors, invalid inputs. |
colorBorder | --druo-border | All borders and dividers. |
colorReward | --druo-reward | Reward/offer pill. |
fontFamily | --druo-font | Whole component. |
borderRadius | --druo-radius | Cards and containers. |
Any raw --druo-* CSS variable can also be passed verbatim.
Rules (appearance.rules) — stable, semantic selectors (internal class names may change; these will not):
.Block, .Input, .Input--valid, .Input--invalid, .Label, .Help, .Error, .Button, .Button--secondary, .Account, .Account--selected, .Tag, .Reward, .Divider, .Trust, .Dialog.
Rules are emitted as a stylesheet scoped with [data-druo-theme="<instanceId>"]. Resolution order: backend component theme → legacy theme → appearance.
Introspection and live updates
Druo.appearance.themes; // ["default","flat","minimal","night"]
Druo.appearance.variables; // friendly variable names
Druo.appearance.selectors; // semantic rule selectors
// Re-theme a mounted component (e.g. your dark-mode switch)
const c = Druo.mount("#druo", { /* … */ });
matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) =>
c.update({ appearance: { theme: e.matches ? "night" : "default" } }),
);Secure fields honour the same appearance object: the values are forwarded to the DRUO-hosted iframe so framed inputs match your page.
Secure fields
By default the account inputs render in the merchant DOM — convenient, but the merchant page can technically read them. With secureFields: true the field group is served from https://js.druo.com inside an iframe: the payer types into DRUO's origin, DRUO tokenizes the values, and only an opaque fieldsToken plus { complete, values: [fieldNames] } cross back over postMessage. The change event still fires so merchant code can gate its own button, and the iframe auto-resizes. Use this whenever the integration must keep bank credentials out of merchant scope.
Locales
Copy resolution order: copy overrides → registered locale → English → key. Register additional languages before mounting:
Druo.locales.register("fr", { "cta.payment": "Payer {amount} par virement" });
Druo.locales.list(); // ["en","es","pt","fr"]The reward rate is not a mount option. It lives on the component configuration in DRUO and arrives with Get Component Details; the badge renders only when the backend returns one.

