@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):

``bash
yarn add @tiptopjar/react-widget
``

Or npm:

`bash
npm install @tiptopjar/react-widget
`

---

🚀 Quick Start

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

export default function App() {
return (



);
}
`

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

---

🎨 Widget Modes

$3

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

`tsx

`

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 |

---

$3

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

`tsx
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) |

---

$3

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

`tsx
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 | ❌ | 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

`tsx


Thanks for reading! Support me with a tip below:


`

---

#### 2️⃣ Floating button on bottom-right

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

---

#### 3️⃣ White button with large text

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

---

⚙️ Next.js Usage

Since this widget injects