@1st-flock/donations-embed-react

React wrapper around the <flock-donate> web component shipped by @1st-flock/donations-embed. Idiomatic React props, typed event handlers, automatic custom-element registration. Works with React 18 and 19 (App Router / Pages Router / Vite / CRA).

Install

npm install @1st-flock/donations-embed @1st-flock/donations-embed-react
# or
pnpm add @1st-flock/donations-embed @1st-flock/donations-embed-react
# or
yarn add @1st-flock/donations-embed @1st-flock/donations-embed-react

react, react-dom, and @1st-flock/donations-embed are peer dependencies. React 18 or 19 is supported.

Quickstart

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

export function GivePage() {
  return (
    <FlockDonate
      publishableKey="pk_test_8xK2zQ9m2nP4rT5vX7yZ"
      mode="inline"
      onComplete={(detail) => {
        console.log("Donation complete:", detail.confirmationId);
      }}
    />
  );
}

Render the page, walk the donor flow, and pay with sandbox card 4111 1111 1111 1111, exp 10/29, CVV 123. The success screen shows a confirmation ID like don_8a1b9c4d. The donation appears in your 1st Flock hub within seconds, marked with a TEST badge — no real money moved.

Importing FlockDonate (or any other symbol from this package) auto-registers the underlying <flock-donate> custom element on window.customElements. There is no separate setup step.

Next.js (App Router)

The component touches window.customElements, which doesn't exist during server rendering. Mark the component or page that uses it as a client component:

"use client";

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

export default function GivePage() {
  return (
    <FlockDonate
      publishableKey="pk_test_8xK2zQ9m2nP4rT5vX7yZ"
      mode="modal"
      triggerLabel="Give"
    />
  );
}

Configuration

Generate keys in the 1st Flock account portal under Donations Setup → Embed Keys (full guide). The wrapper accepts only a publishable key — secret keys are server-only and would be rejected by the underlying web component.

Test mode

Test-mode keys (pk_test_…) route every request to the sandbox cluster. No real money moves. Same code path as production, same webhook events fire. Donations show up in the hub with a TEST badge and never appear in the production ledger.

Props

The wrapper exposes every web-component attribute as a camelCase prop, plus typed event handlers.

| Prop | Type | Notes | | --- | --- | --- | | publishableKey (required) | string | pk_live_… or pk_test_…. | | mode | "inline" \| "modal" \| "drawer" | Render mode. Defaults to "inline". | | triggerLabel | string | Button text for mode="modal" / "drawer". Defaults to "Give". | | funds | string \| string[] \| null | Allowed fund IDs. Empty array hides the picker. | | defaultFund | string \| null | Pre-selected fund ID. | | frequency | string \| FlockDonateFrequency[] | Allowed frequencies. | | defaultFrequency | FlockDonateFrequency | Pre-selected frequency. Defaults to "one-time". | | coverFees | boolean | Show the cover-fees toggle. Defaults to true. | | recurring | boolean | Allow recurring frequencies. Defaults to true. | | theme | "modern" \| "minimal" \| "classic" \| "playful" | Built-in theme preset. Defaults to "modern". | | successMode | "inline" \| "redirect" \| "callback" | Post-donation behaviour. Defaults to "inline". | | successUrl | string \| null | Required when successMode="redirect". | | suggestedAmounts | string \| number[] \| null | Suggested amounts in dollars. | | minAmount | number | Minimum donation in dollars. Defaults to 1. | | maxAmount | number \| null | Maximum donation in dollars. | | language | string | BCP-47 tag. Defaults to "en". | | noAnalytics | boolean | Suppress every host event. |

Plus standard HTML props: className, id, style, and ref (the ref resolves to the underlying <flock-donate> HTMLElement so you can call el.open() / el.close() for modal / drawer modes).

The full attribute reference (including <flock-donate>'s underlying token catalogue and theme inheritance rules) lives at 1stflock.com/developers/donations-embed/.

Event handlers

| Prop | Underlying CustomEvent | When | | --- | --- | --- | | onOpened | flock-donation-opened | Donor opens the flow. | | onStep | flock-donation-step | Donor advances to the next step. | | onComplete | flock-donation-complete | The success screen renders. | | onFailed | flock-donation-failed | The flow fails (declined card, network error). | | onClosed | flock-donation-closed | Donor leaves the flow without completing. |

<FlockDonate
  publishableKey="pk_test_8xK2zQ9m2nP4rT5vX7yZ"
  mode="modal"
  funds={["general", "building", "missions"]}
  defaultFund="general"
  frequency={["one-time", "monthly", "annual"]}
  defaultFrequency="monthly"
  coverFees
  suggestedAmounts={[25, 50, 100, 500]}
  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)}
/>

Setting noAnalytics suppresses every event in the stream — useful when the host platform requires donor consent before any analytics events fire.

Common tasks

Switch render mode

<FlockDonate publishableKey="pk_test_…" mode="inline" />
<FlockDonate publishableKey="pk_test_…" mode="modal" triggerLabel="Give" />
<FlockDonate publishableKey="pk_test_…" mode="drawer" triggerLabel="Support us" />

Theme override

<FlockDonate
  publishableKey="pk_test_…"
  theme="minimal"
  style={{ "--flock-primary": "#0d9488", "--flock-radius": "8px" } as React.CSSProperties}
/>

Imperative open / close (modal / drawer)

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

function GiveButton() {
  const ref = useRef<HTMLElement>(null);
  return (
    <>
      <button onClick={() => ref.current?.dispatchEvent(new MouseEvent("click"))}>
        Open the flow
      </button>
      <FlockDonate
        ref={ref}
        publishableKey="pk_test_…"
        mode="modal"
      />
    </>
  );
}

Bundling notes

The wrapper is ESM-only. Modern bundlers (Vite, Next.js, esbuild, Webpack 5) handle ESM natively. CommonJS-only stacks should use the lower-level @1st-flock/donations-embed web component directly with their bundler's interop layer.

Full documentation

The full reference — theme tokens, integration recipes, webhook event taxonomy, and compliance summary — lives at 1stflock.com/developers/donations-embed/.

Vendor neutrality

This SDK never names the underlying payment processor, bank-link service, or any other third-party vendor in customer-facing strings. The underlying integrations are an implementation detail and may change without notice — your code never has to.

License

MIT — see LICENSE.

Reporting issues

File issues at gitlab.com/1st-flock/donations/-/issues with the label donations-embed-react.