Installation and API

The Givebear SDK is a browser script that renders donation and content widgets on any website. It exposes a single global, window.Givebear. This page lists the served file, the loader pattern, the auto-mount attributes, and every public method exactly as the SDK defines them.

For field-by-field config, see the configuration reference. For copy-paste markup, see snippet examples. For the server-to-server REST API, see Givebear Connect.

The served file

The SDK is served at one URL:

<script src="https://givebear.io/sdk/givebear.js" async></script>

It loads from any origin and browsers cache it for about an hour, so you can drop the tag onto any site.

Loading patterns

Async loader queue

With async (recommended), the script can finish loading after your inline calls run. Define a stub that queues callbacks, then run code inside it. The SDK drains the queue (window.Givebear.q) once the bundle arrives.

<script>
  window.Givebear =
    window.Givebear ||
    function (cb) {
      (window.Givebear.q = window.Givebear.q || []).push(cb);
    };
</script>
<script src="https://givebear.io/sdk/givebear.js" async></script>
<script>
  window.Givebear(function (gb) {
    gb.renderButton("#donate-btn", { organizationId: "your-org-id" });
  });
</script>

Direct calls

If the script is already loaded (no async, or you call from a later script), use window.Givebear as an object and call methods directly.

<script src="https://givebear.io/sdk/givebear.js"></script>
<script>
  window.Givebear.renderButton("#donate-btn", { organizationId: "your-org-id" });
</script>

React

In React, skip the loader entirely: the @givebear/react components load the script once and mount widgets for you. To call a method yourself, loadGivebear() resolves with the same window.Givebear API.

import { loadGivebear } from "@givebear/react";

const gb = await loadGivebear();
gb?.open({ organizationId: "your-org-id" });

Auto-mount

The SDK scans the DOM and mounts any element carrying a data-givebear-* attribute. No JavaScript is required. Mounting runs on DOMContentLoaded, or immediately if the document is already parsed.

<div data-givebear-button data-organization-id="your-org-id"></div>
<script src="https://givebear.io/sdk/givebear.js" async></script>

Each attribute maps to one widget:

The SDK mounts each element once and marks it with data-givebear-mounted="1". You pass config through data-* attributes on the same element (for example data-organization-id, data-fund-id, data-campaign-id). See the configuration reference for the full attribute list.

The window.Givebear API

Every method takes a target (a CSS selector string or a DOM Element) and a config object, except open, track, and version.

If target resolves to no element, the render method does nothing. The config types share a common base; see the configuration reference.

unmount

window.Givebear.unmount(target) tears down the widget mounted in target and clears its mounted marker, so the element can be re-mounted later. Call it when your app removes or re-renders the container (single-page apps, tab switches). React apps get this automatically.

track is a no-op

window.Givebear.track(event, config, metadata?) does nothing. The analytics beacon was removed, but the method is kept so existing embeds that call it do not error. Do not rely on it to record anything. For how the SDK reports its version and loading behavior, see analytics and versioning.

Related