react-kofi-headless

☕️ react-kofi-headless

A headless React wrapper for the Ko-fi overlay widget. Trigger the native Ko-fi donation popup from any custom React component — buttons, links, cards, menus — with full control over positioning.

Ko-fi only provides a fixed, non-customizable button. This library removes that limitation.

Demo Video

Features

• Total UI Freedom: No more fighting with Ko-fi's default floating buttons. You provide the UI
• Single Script Injection: Smartly manages the Ko-fi widget script so it only loads once
• SSR Safe: Built for modern React; handles window checks for Next.js and Remix compatibility
• TypeScript Ready: Full type support for a better developer experience
• Optional Positioning: Anchor the popup to a trigger element or use fixed placements

Quick Start

1. Install the package

npm install react-kofi-headless
# or
yarn add react-kofi-headless

2. Wrap your custom component:

import { KofiOverlay } from 'react-kofi-headless';

const DonateButton = () => (
  <KofiOverlay kofiId="yourname">
    {(open) => (
      <button 
        onClick={open} 
        className="bg-amber-400 p-4 rounded-xl font-bold hover:scale-105 transition-transform"
      >
        Support the Project
      </button>
    )}
  </KofiOverlay>
);

3. Use the hook (Optional): For more complex scenarios, like triggering the overlay from a navbar or a keyboard shortcut.

import { useKofi } from 'react-kofi-headless';

const { open } = useKofi('yourname');

API Reference

<KofiOverlay />

Prop	Type	Description
kofiId	string	Required. Your unique Ko-fi username/ID.
options	KofiOptions	Optional. Configure colors and text for the native popup.
position	PositionOptions	Optional. Configure popup positioning. Default is Ko-fi's behavior.
children	function	Required. Receives open and optional bind helpers.

Positioning

Positioning is best-effort and depends on Ko-fi's internal DOM/classes. If the popup elements are not found, the library logs a warning and falls back gracefully.

PositionOptions

type PositionMode = 'kofi-default' | 'fixed' | 'anchor';
type FixedPlacement = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
type Placement =
  | 'bottom-start' | 'bottom' | 'bottom-end'
  | 'top-start' | 'top' | 'top-end'
  | 'left' | 'left-start' | 'left-end'
  | 'right' | 'right-start' | 'right-end'
  | 'center';

type PositionOptions = {
  mode?: PositionMode;
  placement?: Placement | FixedPlacement;
  offset?: number;
  margin?: number;
  flip?: boolean;
  clamp?: boolean;
  strategy?: 'fixed';
  zIndex?: number;
};

Anchored usage (component)

<KofiOverlay
  kofiId="yourname"
  position={{ mode: 'anchor', placement: 'top-end', offset: 12 }}
>
  {(open, bind) => (
    <button ref={bind?.ref} onClick={open}>
      Donate
    </button>
  )}
</KofiOverlay>

Anchored usage (hook)

const { open } = useKofi('yourname', {
  position: { mode: 'anchor', placement: 'right', offset: 8 },
});

<button onClick={open}>Donate</button>

Open helpers

open(event); // anchors to event.currentTarget
open({ anchorEl }); // anchors to a provided element

Example & Playground

This repository includes a pre-configured example app built with Vite and Tailwind CSS. It demonstrates how to trigger the Ko-fi overlay from:

• Custom gradient buttons.
• Inline text links.
• Interactive cards using the useKofi hook.

To run the example locally:

• From the root directory, run npm run build to compile the library.
• Navigate to the example folder: cd example
• Install dependencies: npm install
• Start the dev server: npm run dev

You can also check out the Live Demo to see the library in action.

Local Development

To play with the code or run the example playground:

• git clone https://github.com/areezvisram/react-kofi-headless.git
• cd react-kofi-headless
• npm install
• npm run build
• cd example && npm run dev

License

This project is licensed under the MIT License.

Built to scratch my own itch. I hope it helps you too! If it does, and you want to support me, I would be very grateful (or just star the repo!) :)