Tapp Swap Widget

React Swap Widget component library for Tapp Exchange.

Usage

Supported Frameworks

• Next.js
• React

Requirements

• React ^18.0.0 or higher

Install

npm install @tapp-exchange/swap-widget

Basic Usage

import { SwapWidget } from '@tapp-exchange/swap-widget'

export default function App() {
  return <SwapWidget/>
}

Advanced Usage

import { SwapWidget } from '@tapp-exchange/swap-widget'

export default function App() {
  return <SwapWidget 
    whitelistedTokens={[
      "0x000000000000000000000000000000000000000000000000000000000000000a",
      "0x8c58fb7fd3ccb2d7bc079dcbf924567fccd385b24b0f8afbfdebf87dc671ba07",
      "0x7538e517af47371976af23a1052bc64172cc65a029d1ef75b453a33d520f0b7f",
    ]}
    defaultToken={'0x000000000000000000000000000000000000000000000000000000000000000a'}
    enableToast={false}
    onSwapSuccess={(data) => {
      console.log("swap success", data);
    }}
    onSwapError={(data) => {
      console.log("swap error", data.error.message);
    }}
  />
}

Props

• whitelistedTokens: string List of token addresses to be displayed. Only these tokens will be shown in the UI
• defaultToken: string The token address that will be selected by default.. default 0x000000000000000000000000000000000000000000000000000000000000000a
• onSwapSuccess: (data: {amountIn: string; amountOut: string; tokenIn: SwapToken; tokenOut: SwapToken}) => void | undefined Callback function that is called when a swap operation is completed successfully.
• onSwapError: (data: {amountIn: string; amountOut: string; tokenIn: SwapToken; tokenOut: SwapToken, error: Error}) => void | undefined: Callback function that is called when a swap operation fails.
• enableToast: boolean An option whether to enable or disable the tapp swap toast. default true

Notes for React with Vite

If you're using React with Vite, you may need to polyfill some Node.js built-in modules.

Install the following plugin:

npm install vite-plugin-node-polyfills --save-dev

Then update your vite.config.ts or vite.config.js:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nodePolyfills } from 'vite-plugin-node-polyfills';

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills()
  ]
});

Styling & Customization

The Tapp Swap Widget uses Tailwind CSS v4 with a custom prefix tapp: to prevent style conflicts with your application. All widget styles are prefixed and scoped to avoid interfering with your existing CSS.

CSS Architecture

• Prefix: All Tailwind classes use the tapp: prefix
• Scoped Styles: Widget styles are contained within the component
• Custom Properties: CSS variables are used for colors and theming
• Fonts: Custom fonts (SFPro, Sen) are loaded via CDN

Method 1: CSS Custom Properties (Recommended)

Override the CSS variables used by the widget:

/* Override widget color scheme */
:root {
  --tapp-color-tapp-white: #FFFFFF;
  --tapp-color-tapp-gray: #333333;
  --tapp-color-tapp-pink: #FF69B4;
  --tapp-color-tapp-purple-light: #9932CC;
  --tapp-color-tapp-green: #32CD32;
  --tapp-color-tapp-black: #000000;
}

/* Override specific component colors */
.tapp-swap-widget {
  --tapp-color-tapp-reskin-gray: #4A4A4A;
  --tapp-color-tapp-reskin-black: #1A1A1A;
  --tapp-color-tapp-pool-bg: #2A2A2A;
}

Method 2: CSS Specificity Override

Use higher specificity to override specific widget styles:

/* Override input box background */
.tapp-swap-widget .tapp\:bg-swap-input-box {
  background: #2A2A2A;
}

/* Override button styles */
.tapp-swap-widget button[class*="tapp:"] {
  border-radius: 8px;
  font-weight: 600;
}

/* Override text colors */
.tapp-swap-widget .tapp\:text-tapp-white {
  color: #FFFFFF;
}

Method 3: Component-Level Styling

Target specific widget components:

/* Style the main widget container */
.tapp-swap-widget {
  border: 1px solid #333;
  border-radius: 12px;
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
}

/* Style token selection buttons */
.tapp-swap-widget [aria-label="select token"] {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

/* Style swap input fields */
.tapp-swap-widget input[type="number"] {
  font-size: 18px;
  font-weight: 500;
}

/* Style dialog */
.tapp-dialog [aria-label='search input'] {
  border-color: #1A1A1A;
}

Available CSS Variables

Colors

--tapp-color-tapp-white: #FFF0F5;
--tapp-color-tapp-gray: #343434;
--tapp-color-tapp-pink: #FBA1B7;
--tapp-color-tapp-purple-light: #A367E7;
--tapp-color-tapp-green: #00CB9A;
--tapp-color-tapp-black: #2F2F2F;
--tapp-color-tapp-reskin-gray: #3f3f3f;
--tapp-color-tapp-reskin-black: #1b1b1b;

Fonts

--tapp-font-sf: "SFPro", "Sen", "sans-serif";
--tapp-font-sen: "Sen", "sans-serif";

Layout

--tapp-radius: 0.5rem;
--tapp-breakpoint-xs: 393px;
--tapp-breakpoint-3xl: 1792px;

Theme Integration Examples

Dark Theme

.dark .tapp-swap-widget {
  --tapp-color-tapp-white: #1a1a1a;
  --tapp-color-tapp-black: #ffffff;
  --tapp-color-tapp-gray: #f0f0f0;
}

Light Theme

.light .tapp-swap-widget {
  --tapp-color-tapp-white: #ffffff;
  --tapp-color-tapp-black: #000000;
  --tapp-color-tapp-gray: #333333;
}

Custom Border Effects

The widget uses custom gradient borders. To override:

/* Override swap input border gradient */
.tapp-swap-widget .tapp\:border-swap::before {
  background: linear-gradient(to right, #your-color1, #your-color2);
}

/* Override focused state border */
.tapp-swap-widget .tapp\:border-swap-focus::before {
  background: linear-gradient(to right, #your-focus-color1, #your-focus-color2);
}

Typography Override

/* Override all widget text */
.tapp-swap-widget * {
  font-family: 'Your Custom Font', sans-serif;
}

/* Override specific text elements */
.tapp-swap-widget h1,
.tapp-swap-widget h2,
.tapp-swap-widget h3 {
  font-family: 'Your Header Font', serif;
}

Responsive Overrides

/* Mobile customization */
@media (max-width: 393px) {
  .tapp-swap-widget {
    padding: 12px;
    margin: 8px;
  }
}

/* Desktop customization */
@media (min-width: 1792px) {
  .tapp-swap-widget {
    max-width: 500px;
    margin: 0 auto;
  }
}

Best Practices

1. Use CSS Custom Properties: Prefer overriding CSS variables over direct style overrides
2. Maintain Specificity: Use container classes to scope your overrides
3. Test Responsiveness: Ensure your customizations work on all screen sizes
4. Preserve Accessibility: Don't override focus states without providing alternatives
5. Performance: Avoid overly complex selectors that could impact performance

Troubleshooting

Styles Not Applying

• Ensure your CSS has higher specificity than the widget's styles
• Use !important sparingly and only when necessary
• Check that your CSS is loaded after the widget's CSS

Responsive Issues

• Test your overrides across different screen sizes
• Use the same breakpoints as the widget for consistency
• Consider the widget's responsive behavior when applying overrides

Font Loading Issues

• Ensure custom fonts are properly loaded before the widget renders
• Provide fallback fonts in your font stack
• Consider font loading performance impact

Development

Installation

npm install --legacy-peer-deps

Build

npm run build

Docker

You can run the widget demo using Docker:

# Build the Docker image
docker build . -t "tapp-widget-demo"

# Run the container
docker run -p 3000:3000 tapp-widget-demo

The demo will be available at http://localhost:3000