@tiptopjar/react-widget

React component library for embedding Tip Top Jar widgets into your website — the easiest way to let users leave you a tip 💸.

⚙️ Requirements

To use this package, you need a Tip Top Jar account.

You can:

1. Embed widgets directly using the embed code provided on your Tip Top Jar dashboard, or
2. Integrate programmatically using this developer package (@tiptopjar/react-widget).

Sign up or log in at 👉 https://tiptopjar.com

🧭 Table of Contents

1. Overview
2. Installation
3. Quick Start
4. Widget Modes
   • Inline Mode
   • Floating Mode
   • Button Mode
5. Props Reference
6. Examples
7. Next.js Usage
8. Customization Tips
9. FAQ
10. License

⚡ Overview

@tiptopjar/react-widget makes it easy for React developers to embed Tip Top Jar widgets directly into their apps.

It supports three distinct widget modes:

| Mode | Description | |------|--------------| | 🧱 Inline | Renders a full Tip Top Jar card directly in your page content. | | 🎈 Floating | Displays a round floating “Tip” button that opens a side modal. | | 💬 Button | Creates a pill-style link button to your Tip Top Jar page. |

📦 Installation

Using Yarn (recommended):

yarn add @tiptopjar/react-widget

Or npm:

npm install @tiptopjar/react-widget

🚀 Quick Start

import { TipTopJarEmbed } from '@tiptopjar/react-widget';

export default function App() {
  return (
    <div>
      <h2>Support my work ❤️</h2>
      <TipTopJarEmbed username="yourusername" mode="inline" />
    </div>
  );
}

💡 No API keys or configuration needed — just your Tip Top Jar username.

🎨 Widget Modes

🧱 Inline Mode

Inline mode embeds a complete Tip Top Jar card directly in your layout.

<TipTopJarEmbed username="hamza" mode="inline" />

Optional props

| Prop | Type | Default | Description | | ----------- | ------------------- | ----------- | --------------------------------------------- | | origin | string | auto-detect | Override base domain (for advanced use cases) | | className | string | — | Apply custom class to wrapper div | | style | React.CSSProperties | — | Inline styling for wrapper |

🎈 Floating Mode

Floating mode adds a round floating button that toggles a side modal Tip Jar card.

<TipTopJarEmbed
  username="hamza"
  mode="floating"
  position="bottom-right"
  message="Fuel my work 🔥"
  xMargin={20}
  yMargin={20}
/>

Optional props

| Prop | Type | Default | Description | | ---------- | --------------------------------- | --------------- | ------------------------------------ | | position | 'bottom-left' \| 'bottom-right' | 'bottom-left' | Where to anchor the floating button | | xMargin | number | 18 | Horizontal offset | | yMargin | number | 18 | Vertical offset | | message | string | "Leave a tip" | Tooltip text shown near button | | origin | string | auto-detect | Base domain (for advanced use cases) |

💬 Button Mode

Button mode renders a standalone pill-style button linking to your Tip Top Jar page.

<TipTopJarEmbed
  username="hamza"
  mode="button"
  buttonColor="black"
  buttonSize="md"
  buttonText="Send a Tip"
/>

Optional props

| Prop | Type | Default | Description | | ------------- | ---------------------- | -------------- | ------------------------------------ | | buttonColor | 'black' \| 'white' | 'black' | Button color theme | | buttonSize | 'sm' \| 'md' \| 'lg' | 'md' | Button size | | buttonText | string | "Send a Tip" | Text label on the button | | origin | string | auto-detect | Base domain (for advanced use cases) |

🧩 Props Reference

All widgets share these common props:

| Prop | Type | Required | Description | | ----------- | ----------------------------------------- | -------- | ------------------------------------------------ | | username | string | ✅ | Your Tip Top Jar username | | mode | 'inline' \| 'floating' \| 'button' | ✅ | Widget type | | origin | string | ❌ | Override default domain (for advanced use cases) | | data | Record<string, string | number | boolean> | ❌ | Pass through extra data-* attributes | | widgetSrc | string | ❌ | Custom URL for widget loader script | | className | string | ❌ | Custom class for wrapper div | | style | React.CSSProperties | ❌ | Inline style for wrapper div |

💡 Examples

1️⃣ Inline in a blog post

<article>
  <p>Thanks for reading! Support me with a tip below:</p>
  <TipTopJarEmbed username="hamza" mode="inline" />
</article>

2️⃣ Floating button on bottom-right

<TipTopJarEmbed
  username="hamza"
  mode="floating"
  position="bottom-right"
  message="Leave a tip!"
/>

3️⃣ White button with large text

<TipTopJarEmbed
  username="hamza"
  mode="button"
  buttonColor="white"
  buttonSize="lg"
  buttonText="Buy me a coffee ☕"
/>

⚙️ Next.js Usage

Since this widget injects <script> tags, it must run client-side only.

In Next.js 13+, use it inside a Client Component:

'use client';

import { TipTopJarEmbed } from '@tiptopjar/react-widget';

export default function Page() {
  return <TipTopJarEmbed username="hamza" mode="floating" />;
}

🧠 Customization Tips

• All widgets are loaded via our hosted widget.js file, so you don’t need to include scripts manually.
• Multiple widgets on one page are fully supported — each loads independently.
• The origin prop is optional and only needed if you are using a custom domain.

❓ FAQ

Q: Do I need Vite or special tooling? A: Nope. Your app just imports the built React component. Works with CRA, Next.js, Remix, or Vite.

Q: Can I show multiple widgets on one page? A: Absolutely! Each instance is sandboxed and loads its own configuration.

Q: Can I style the internal widget? A: Internal widget styling is isolated (iframe-based) to ensure brand consistency, but you can style the wrapper or surrounding layout freely.

Q: What if I’m not seeing the widget load? A: Make sure your username and mode props are both set, and that you have a valid Tip Top Jar account.

📜 License

MIT © Tip Top Jar

💬 Feedback & Contributions

We’d love to hear from you! Open an issue or PR on GitHub: 👉 https://github.com/tiptopjar/react-widget