Browser Embed

The browser embed is a single web component, <flock-donate>, that renders the entire donor flow — amount selection, fund picker, donor info, payment, and confirmation — inside Shadow DOM on any page. A thin React wrapper, <FlockDonate>, is provided for React and Next.js projects; it forwards every attribute and surfaces every event as a familiar on* prop.

Embedded giving is one-time only. Recurring giving is available through your organisation's 1st Flock account experience, where donors can view, update, and cancel their schedules.

This page is the complete reference for both. For a 5-minute walkthrough that gets the embed live on your page, see Getting Started. For platform-specific paste instructions, see Integration Examples.

Installation

<script type="module" src="https://payments.1stflock.com/v1.js"></script>

:::

Web component reference

The <flock-donate> element accepts fifteen attributes. The minimum to render anything is publishable-key; everything else has a sensible default.

publishable-key (required)

Your pk_live_… or pk_test_… publishable key. The embed validates the prefix on mount and refuses to render with anything else (secret keys, malformed strings, empty values).

<flock-donate publishable-key="pk_test_REPLACE_ME"></flock-donate>

mode

Controls how the donor flow is presented on the page.

<flock-donate publishable-key="pk_test_REPLACE_ME" mode="modal"></flock-donate>

For modal and drawer modes, the launcher button label is controlled by the trigger-label attribute.

trigger-label

Text on the launcher button when mode="modal" or mode="drawer". Ignored in inline mode. Defaults to Give.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  mode="modal"
  trigger-label="Give to the Building Fund"
></flock-donate>

funds

Comma-separated list of fund IDs the donor is allowed to give to. When omitted, the embed loads every active fund from your organisation. Setting it to an empty string (funds="") hides the fund picker entirely and routes everything to your default fund.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  funds="general,building,missions"
></flock-donate>

default-fund

The fund ID that should be pre-selected when the donor opens the flow. Must be one of the IDs in the funds list (or, if funds is omitted, any fund on your organisation). When omitted, the organisation's default fund is pre-selected.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  default-fund="building"
></flock-donate>

cover-fees

When true (default), the donor sees a "Cover the processing fee?" checkbox at the confirmation step. When false, the checkbox is hidden and the donor never sees a fee-coverage option.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  cover-fees="false"
></flock-donate>

theme

Selects one of four built-in style presets. These set the base palette, type scale, button style, and corner radius. Detailed customisation is available via the Theme tab in the Hub portal.

<flock-donate publishable-key="pk_test_REPLACE_ME" theme="minimal"></flock-donate>

success-mode

Controls what happens after the donor reaches the success screen.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  success-mode="redirect"
  success-url="/give/thanks"
></flock-donate>

success-url

Required when success-mode="redirect". Ignored otherwise. Can be an absolute URL (https://example.org/thanks) or a path on your own site (/give/thanks). The confirmation ID is appended as ?confirmation_id=… so your destination page can look up the donation if you want to render a personalised thank-you.

suggested-amounts

Comma-separated list of suggested amount chips, in dollars (not cents). Donors can still enter a custom amount even when chips are present. When omitted, the chips are taken from the organisation's defaults configured in the Hub.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  suggested-amounts="25,50,100,500"
></flock-donate>

min-amount

Minimum donation amount, in dollars. The donor cannot submit anything below this. Defaults to 1.

<flock-donate publishable-key="pk_test_REPLACE_ME" min-amount="5"></flock-donate>

max-amount

Maximum donation amount, in dollars. The donor cannot submit anything above this. Defaults to no upper limit.

<flock-donate publishable-key="pk_test_REPLACE_ME" max-amount="10000"></flock-donate>

language

A BCP-47 language tag for the embed UI. Currently supports en (default). Additional languages are tracked on the public roadmap.

data-no-analytics

When present (any value), suppresses the entire host event stream. Use this when your hosting platform requires donor consent before any analytics events fire and consent has not yet been granted.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  data-no-analytics
></flock-donate>

trust-footer

When true (default), the donor flow renders a small trust footer at the bottom of the card reading "🔒 Bank-grade encryption · PCI DSS Level 1 · Processed by 1st Flock". When false, the footer is hidden — useful for white-label deployments where the customer's brand alone should anchor donor confidence.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  trust-footer="false"
></flock-donate>

The footer can also be hidden at the organisation level by setting trust_footer_visible: false in the Hub theme JSON. The HTML attribute (deployment-time) wins over the Hub setting (account-level default), so a single page can override the org default.

Note: The <FlockDonate> React wrapper in v1.0.0 does NOT yet expose this prop. To use it from React, set the attribute imperatively via ref:

const ref = useRef<HTMLElement>(null);
useEffect(() => {
  ref.current?.setAttribute("trust-footer", "false");
}, []);
return <FlockDonate ref={ref} publishableKey="..." />;

First-class trustFooter prop support is tracked for the next minor release of the React wrapper.

React wrapper

The React wrapper exposes the web-component attributes as React props (camelCase) plus typed event handlers (on*). The trust-footer attribute is the one omission (see the note above for the ref workaround).

import { FlockDonate } from "@1st-flock/donations-embed-react";

<FlockDonate
  publishableKey="pk_test_REPLACE_ME"
  mode="modal"
  triggerLabel="Give"
  funds={["general", "building", "missions"]}
  defaultFund="general"
  coverFees
  theme="modern"
  successMode="callback"
  suggestedAmounts={[25, 50, 100, 500]}
  minAmount={5}
  maxAmount={5000}
  language="en"
  onOpened={(detail) => console.log("opened", detail)}
  onStep={(detail) => console.log("step", detail)}
  onComplete={(detail) => analytics.track("donation", detail)}
  onFailed={(detail) => console.error("failed", detail)}
  onClosed={(detail) => console.log("closed", detail)}
/>

The wrapper accepts arrays for the comma-list attributes (funds, suggestedAmounts) and serialises them automatically. Strings are also accepted if you prefer to pass "general,building,missions" directly.

ref resolves to the underlying <flock-donate> HTMLElement so you can imperatively call el.open() / el.close() for mode="modal" and mode="drawer".

For React 18+, the component renders client-side only — it touches window.customElements, which does not exist during SSR. In Next.js App Router, mark the parent component or page as a client component with "use client".

Render modes

Inline

The flow renders inline at the spot where you placed the element. Use this when the entire purpose of the page (or a major section) is donating — for example, a "Give" page or a "Support our mission" landing page.

<flock-donate publishable-key="pk_test_REPLACE_ME" mode="inline"></flock-donate>

The flow occupies a card with rounded corners and a soft shadow, sized to fit the available width up to a maximum of approximately 480 pixels.

Modal

A launcher button renders inline; clicking it opens the flow in a centred modal overlay with a backdrop. Use this when donation is one of many calls-to-action on a page (for example, an "About" page with a "Support us" button).

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  mode="modal"
  trigger-label="Support our work"
></flock-donate>

The modal locks scroll on the host page while open, traps focus inside the flow, and dismisses on Escape or backdrop click.

Drawer

A launcher button renders inline; clicking it slides the flow in from the right edge of the viewport. Use this in app-style layouts (sidebar nav, top header) where a centred modal would feel out of place.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  mode="drawer"
  trigger-label="Give"
></flock-donate>

The drawer behaves like the modal in every other respect (scroll lock, focus trap, Escape to dismiss).

Theming and brand

The embed's appearance is determined by a four-layer precedence chain. Each layer overrides the one above it, so a host can pick a preset and surgically override only the tokens that matter.

1. Built-in defaults — sensible values shipped with the embed.
2. Preset — the theme attribute (modern, minimal, classic, playful).
3. Hub theme JSON — values configured in Donations Embed → Theme in the Hub. Persists per organisation.
4. CSS custom properties — values set on the <flock-donate> host element via inline style= or external CSS take precedence over everything else.

The custom-property overrides are the escape hatch for "I want this exact shade of teal even though our preset is modern" cases.

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  style="
    --flock-primary: #0d9488;
    --flock-primary-foreground: #ffffff;
    --flock-radius: 8px;
  "
></flock-donate>

The full token catalogue is exposed via custom properties prefixed --flock-. The most useful ones:

For per-organisation persistence and a visual editor, configure the theme JSON in the Hub portal.

Events and success modes

The embed dispatches five CustomEvents on the host element, all with bubbles: true and composed: true so they escape Shadow DOM and reach window-level analytics listeners.

Plain HTML / vanilla JS:

<flock-donate publishable-key="pk_test_REPLACE_ME"></flock-donate>
<script>
  window.addEventListener("flock-donation-complete", (event) => {
    const { confirmationId, amount, fund } = event.detail;
    console.log(`Donor gave $${amount} to ${fund.name} (${confirmationId})`);
  });
</script>

React:

<FlockDonate
  publishableKey="pk_test_REPLACE_ME"
  onComplete={(detail) => {
    console.log(`Donor gave $${detail.amount} (${detail.confirmationId})`);
  }}
/>

Three success modes

The three modes are not exclusive — flock-donation-complete fires for inline and redirect too. The difference is that callback mode never auto-redirects, so your handler is the only thing that runs after the success screen.

Browser support

The embed targets evergreen browsers (Chrome, Edge, Firefox, Safari) on the last two major versions plus the current LTS Node version for SSR-side checks. Internet Explorer is not supported. Mobile Safari and Chrome on Android are first-class targets.

The embed depends on standard web platform features (Custom Elements, Shadow DOM, fetch, ES2020). No polyfills are loaded by default. If you need to support an older runtime, surface that requirement to your developer team — most older runtimes will need either a transpilation step or a polyfill bundle, neither of which is shipped with the embed.

Next steps

• Integration Examples — step-by-step guides for WordPress, Squarespace, Wix, plain HTML, React, and Next.js.
• Webhooks — receive donation events server-side with signed delivery.
• Compliance & Security — CSP / SRI guidance and the customer obligations summary.