> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tipstack.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed the Tip Stack Widget on Any Website

> Add a Tip Stack tipping button to any website with two lines of HTML. Customize the theme and accent color without any JavaScript framework required.

The Tip Stack widget is an embeddable iframe that renders a tipping button anywhere on the web — no JavaScript framework, no build step, no backend required. Paste two lines of HTML into any page and your audience can tip you on Solana in seconds.

## How it works

When your page loads, `widget.js` scans for any element carrying a `data-tipstack-id` attribute, injects a styled button in its place, and opens a sandboxed Tip Stack checkout inside an iframe when a visitor clicks it. Payments flow non-custodially from supporter to your wallet — the widget never holds funds.

## Embed the widget

<Steps>
  <Step title="Copy the snippet">
    Paste the following HTML wherever you want the tipping button to appear. Replace the placeholder values with your own handle, preferred theme, and accent color.

    ```html index.html theme={null}
    <div
      data-tipstack-id="YOUR_HANDLE_OR_WALLET"
      data-tipstack-theme="dark"
      data-tipstack-color="#00D265">
    </div>
    <script src="https://tipstack.fun/widget.js"></script>
    ```
  </Step>

  <Step title="Whitelist your domain">
    Before you deploy to production, add your site's origin to the allowed-domains list in your creator dashboard. The widget will refuse to load on any origin that is not whitelisted.

    <Note>
      Add your domain to the whitelist in your creator dashboard before deploying the widget in production.
    </Note>

    See [Origin Whitelist](/embed/origin-whitelist) for step-by-step instructions.
  </Step>

  <Step title="Publish your page">
    Deploy your HTML as normal. When a visitor lands on your page they will see a ⚡ **Tip me on Tip Stack** button styled in your chosen accent color. Clicking it opens the hosted Tip Stack checkout inside a sandboxed iframe.
  </Step>
</Steps>

## Data attributes

Customize the widget's appearance and identity using HTML data attributes on the container `<div>`.

| Attribute             | Required | Description                                                                      |
| --------------------- | -------- | -------------------------------------------------------------------------------- |
| `data-tipstack-id`    | Yes      | Your creator handle (e.g. `satoshi`), Solana wallet address, or numeric user ID. |
| `data-tipstack-theme` | No       | Color scheme for the checkout iframe. Accepts `dark` (default) or `light`.       |
| `data-tipstack-color` | No       | Hex accent color applied to the button and checkout UI. Defaults to `#00D265`.   |

### Accent color presets

The creator dashboard offers six built-in swatches you can copy directly into your snippet:

<CardGroup cols={3}>
  <Card title="Green" icon="circle">
    `#00D265` — default brand color
  </Card>

  <Card title="Red" icon="circle">
    `#FF3B30` — bold call to action
  </Card>

  <Card title="Indigo" icon="circle">
    `#5865F2` — Discord-style
  </Card>

  <Card title="Sky" icon="circle">
    `#1DA1F2` — Twitter / X blue
  </Card>

  <Card title="Orange" icon="circle">
    `#FF9500` — warm contrast
  </Card>

  <Card title="Purple" icon="circle">
    `#AF52DE` — creator purple
  </Card>
</CardGroup>

## What the button looks like

The button renders as a rounded pill containing a **lightning bolt icon** on the left and the label **"Tip me on Tip Stack"** in bold. The background is filled with your chosen accent color and the text is dark for maximum contrast. It is fully responsive and scales correctly on mobile without any extra CSS.

## Where to place it

You can drop the snippet into virtually any HTML surface:

<CardGroup cols={2}>
  <Card title="Blog or personal site" icon="newspaper">
    Place it at the bottom of each post to let readers tip after they finish reading.
  </Card>

  <Card title="Linktree alternative page" icon="link">
    Add it alongside your social links so fans have a direct way to support you.
  </Card>

  <Card title="Notion embed" icon="file">
    Paste the snippet into a Notion page via the HTML embed block.
  </Card>

  <Card title="GitHub profile README" icon="code">
    Embed the action button in your `README.md` using a linked badge or raw HTML.
  </Card>
</CardGroup>

## Share your bio link

Every Tip Stack creator also gets a standalone profile page at:

```
https://tipstack.fun/YOUR_HANDLE
```

Share this URL directly in your **Instagram bio**, **Twitter/X bio**, or **YouTube description** — no embed required. Visitors land on your full-featured Tip Stack profile where they can tip in SOL, USDC, or fiat.

## Security

When the widget initializes, the Tip Stack server validates that the embedding page's origin matches your whitelisted domains. If the origin is not recognized, the widget silently refuses to render and the server returns a `403 Unauthorized Origin` response.

<Note>
  `localhost` and `127.0.0.1` are automatically allowed during development — you do not need to add them to your whitelist.
</Note>

For full details on managing allowed origins, see [Origin Whitelist](/embed/origin-whitelist).