> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Branding, language, and form options

> Customize the Pay with WeGive button and hosted pop-up with themes, translations, and donor-flow settings.

## Build a theme in the dashboard

Open **Settings → Pay Playground** after your organization has access. Choose
**Test donations**, configure the pop-up, and copy the generated integration
snippet. Replace its key placeholder with your matching publishable key from
**Pay SDK Keys**. Selecting **Live donations** changes the key placeholder; it
does not switch your account's processing mode by itself.

To start with a saved organization theme, select **Load organization themes**,
choose a theme, and select **Use this theme**. This prefills supported colors,
control styles, fonts, and logo. Loading themes requires theme-read permission.

The pop-up theme is a copy you can customize independently. Editing it does not
modify the saved organization theme, and later changes to the source theme do not
automatically change your copied configuration.

## Apply a theme in code

Pass `theme` to `mountButton()` or `open()`:

```js theme={null}
const popupTheme = {
  mode: 'auto',
  radius: '10px',
  inputRadius: '6px',
  buttonRadius: '999px',
  popupRadius: '16px',
  font: 'Inter, system-ui, sans-serif',
  fontUrl: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap',
  logo: {
    light: 'https://giving.example.org/assets/logo-dark.svg',
    dark: 'https://giving.example.org/assets/logo-light.svg',
  },
  light: {
    brand: '#245c48', brandFg: '#ffffff',
    bg: '#ffffff', surface: '#f3f6f4', text: '#17251e',
  },
  dark: {
    brand: '#93d4b8', brandFg: '#10291d',
    bg: '#15231c', surface: '#1c3025', text: '#f5faf7',
  },
  copy: {
    title: 'Support lasting change',
    subtitle: 'Your generosity makes our work possible.',
    action: 'Give',
  },
  locale: 'en',
  showLocalePicker: true,
  paymentMethods: { allowCard: true, allowBank: true },
  billing: { fields: 'full' },
};

pay.mountButton('#donate', {
  amount: 5000,
  label: 'Give today',
  theme: popupTheme,
});
```

Replace image URLs with publicly accessible HTTPS assets. `logo` and `avatar`
accept either a single URL or an object containing `light` and `dark` URLs.
`avatar` supplies the fallback image for the donor's giving-profile chip.

`mode` accepts `light`, `dark`, or `auto`. A fixed mode hides the theme toggle;
`auto` lets the donor switch. Unspecified tokens use the pop-up defaults. Define
both light and dark tokens when supporting both appearances.

`font` is a CSS font stack. To load a webfont, supply its HTTPS stylesheet in
`fontUrl`; a font-family name alone does not download a font. Your organization
is responsible for using licensed fonts and accessible colors.

## Color and shape reference

Set color tokens separately inside `theme.light` and `theme.dark`:

| Tokens | Surface |
| - | - |
| `brand`, `brandHover`, `brandFg`, `brandSoft` | Accent, hover accent, text on the accent, and soft accent backgrounds |
| `bg`, `surface` | Main and secondary backgrounds |
| `text`, `textMuted`, `textPlaceholder` | Main, secondary, and placeholder text |
| `border`, `borderMuted`, `focus` | Borders, dividers, and focus indication |
| `inputBg`, `inputDisabledBg`, `inputText` | Input backgrounds and text |
| `inputBorder`, `inputFocus`, `inputPlaceholder` | Input borders, focus, and placeholder color |
| `buttonBg`, `buttonHover`, `buttonText` | Button-specific colors |

Use `theme.radius` for shared rounding, or `inputRadius`, `buttonRadius`, and
`popupRadius` for separate control shapes. Values are CSS lengths such as `8px`
or `0.5rem`.

## Style the launch button

Button options are separate from the full pop-up theme:

| Option | Behavior |
| - | - |
| `label` | Required button text |
| `logo` | Override the button's organization image |
| `hideLogo` | Hide the leading image or organization mark |
| `brand.color`, `brand.foreground` | Button background and text colors; also provide simple pop-up branding |
| `brand.radius`, `brand.font` | Button radius and font; simple pop-up defaults |
| `className` | Your host-page CSS classes; replaces the automatic button styling |
| `theme` | Detailed pop-up appearance; takes precedence over overlapping simple brand values inside the pop-up |

Your page must provide the CSS for any classes you pass. Host-page CSS does not
reach inside the hosted pop-up or Payframes. For a fully custom launch button,
render your own element and call `pay.open()`.

## Languages and copy

Built-in `theme.locale` values are `en`, `es`, `fr`, `de`, `pt`, `nl`, and `it`.
If omitted, the pop-up uses a supported browser language, falling back to English.
Set `showLocalePicker: true` to let donors change languages in checkout.

Use `theme.copy.title`, `subtitle`, and `action` for prominent checkout copy.
`action` is the verb used in the amount-bearing donation button. Use
`theme.strings` to override individual labels. Overrides take precedence over
built-in translations, so a fixed custom string is not automatically translated
when the donor changes language.

```js theme={null}
const languageOptions = {
  locale: 'es',
  strings: {
    continueAction: 'Continuar',
    receiptHeadline: '¡Gracias por tu generosidad!',
    receiptPending: 'Tu donación está pendiente de confirmación.',
  },
};
```

These are the available string override keys:

| Area | Keys |
| - | - |
| Sign-in and navigation | `emailHeadingLogin`, `emailHeadingSignup`, `verifyHeading`, `resendCode`, `verifying`, `continueAction` |
| Giving profile | `givingAsHeader`, `giveAsHeader`, `addNewProfile`, `addProfile` |
| Payment methods | `paymentMethodHeader`, `paymentMethodsHeader`, `addPaymentMethod`, `saveCard`, `saveBank`, `saveAccount`, `saving`, `cancel` |
| Completion | `receiptHeadline`, `receiptPending`, `receiptScheduled`, `receiptSubtitle` |
| Footer and disclosure | `securityNote`, `termsLink`, `privacyLink`, `recaptchaDisclosure`, `recaptchaPrivacyLabel`, `recaptchaTermsLabel` |
| Validation | `fieldRequired`, `errorCardNumber`, `errorCardExpiration`, `errorCardCvv`, `errorCardDetails`, `errorBillingAddress`, `errorRoutingNumber`, `errorRoutingChecksum`, `errorAccountNumber`, `errorTransitNumber`, `errorInstitutionNumber`, `errorGeneric`, `errorFormLoading` |

If overriding `recaptchaDisclosure`, retain both `{privacy}` and `{terms}`
placeholders so their disclosure links remain present. Localized copy changes
presentation; it does not change payment eligibility, currency, or legal terms.

## Donor and payment-form options

| Option | Default | Effect |
| - | - | - |
| `theme.signup.allowCompany` | `false` | Offer a company giving profile during signup |
| `theme.signup.companyLabel` | Built-in label | Customize the company option's wording |
| `theme.signup.allowGuest` | `false` | Offer guest checkout without remembering the donor's sign-in session |
| `theme.signup.guestLabel` | Built-in label | Customize the guest option's wording |
| `theme.paymentMethods.allowCard` | `true` | Show card entry where supported |
| `theme.paymentMethods.allowBank` | `true` | Show bank entry where supported |
| `theme.paymentMethods.allowBankLogin` | `false` | Show bank-login connection when configured for your account |
| `theme.billing.fields` | `full` | Use `full` address collection or `minimal` name and postal-code collection |

Payment-method options control the entry UI; they do not enable a processor or
add account capabilities. Keep at least one supported method available. Confirm
minimal billing is appropriate for your processor. Guest mode does not bypass
payment verification or fraud checks.

## Organization brand versus appearance

Use `organizationBrandId` in the donation options to identify the donation's
financial brand. Set `theme` to control how checkout looks. A theme, logo, or
language selection does not select an organization, financial brand, processing
currency, or payment processor. The publishable key identifies your organization.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.