Installation and Configuration Buycoin Smart Widget

Installation

npm install smart-buycoin-widget
# or
yarn add smart-buycoin-widget

Peer Dependencies

Ensure the following dependencies are installed in your project:

npm install react react-dom wagmi @tanstack/react-query viem
# or
yarn add react react-dom wagmi @tanstack/react-query viem

⚙️ Configuration (PublicConfig)

The SmartBuycoinWidget component accepts a primary configuration object describing the behavior, available networks, and appearance of the widget.

PublicConfig Properties

Property	Type	Required	Description
integrator	string	✅	A unique integrator identifier. Required for analytics and fee attribution.
chains	number[]	✅	Array of network IDs available to the user. Use `NetworkId` for convenience.
appearance	`'light'	'dark'	'system'`
theme	`BuycoinWidgetTheme`	❌	Object for fine-tuning styles (MUI Theme).
disableDefaultTheme	boolean	❌	If `true`, disables the built-in Buycoin theme. Your theme fully replaces all styles. Default: `false`.

🎨 Theming & Merge Logic

Theming (BuycoinWidgetTheme)

The theme object allows complete visual customization of the widget using Material UI specification.

Field	Type	Description
palette	`PaletteOptions`	Global color palette (primary, secondary, background, text).
colorSchemes	`{ light: ..., dark: ... }`	Scheme-specific palettes.
shape	`Shape`	Border radius configuration.
typography	`TypographyVariantsOptions`	Font settings (family, weight, size).
container	`CSSProperties`	Styles for the widget's outer container.
header	`CSSProperties`	Styles for the widget header.
components	`WidgetThemeComponents`	Overrides for specific UI components.
navigation	`{ edge?: boolean }`	Navigation appearance (corner rounding).

Customizable Components

Inside components, you may override styles for:

MuiAppBar (Header)
MuiButton (Buttons)
MuiCard / MuiInputCard (Cards)
MuiAvatar (Icons)
MuiTabs / MuiNavigationTabs (Navigation)
MuiCheckbox (Checkboxes)

📝 Full Configuration Example

import { SmartBuycoinWidget, NetworkId, type PublicConfig } from 'smart-buycoin-widget';

const config: PublicConfig = {
  // 1. Required parameters
  integrator: 'your-dapp-name',
  chains: [
    NetworkId.ETH,
    NetworkId.BSC,
    NetworkId.ARB,
    NetworkId.SOL
  ],

  // 2. Appearance mode
  appearance: 'dark',

  // 3. Style customization
  theme: {
    palette: {
      primary: { main: '#306CDD' },
      secondary: { main: '#F5B544' },
      background: {
        default: '#1F1F1F', // Widget background
        paper: '#2A2A2A',   // Card background
      },
      text: { primary: '#FFFFFF' }
    },
    shape: {
      borderRadius: 16,
    },
    typography: {
      fontFamily: 'Inter, sans-serif',
    },
    container: {
      border: '1px solid #333',
      boxShadow: '0px 4px 20px rgba(0,0,0,0.5)',
    },
    components: {
      MuiButton: {
        styleOverrides: {
          root: {
            fontWeight: 700,
            textTransform: 'none',
          },
        },
      },
    },
  },
};

export const SwapPage = () => {
  return <SmartBuycoinWidget {...config} />;
};

Widget Theme Modes

The widget supports two theme-handling modes:

1. Partial Modification (Deep Merge) — default

If disableDefaultTheme is omitted or false, your theme is merged with the built-in Buycoin theme (blue colors, radius 16px).

Best for:
Small adjustments (e.g., making buttons red) while keeping the rest of the Buycoin look.

Example: Change only button color

const config: PublicConfig = {
  integrator: 'my-app',
  chains: [1, 56],
  theme: {
    palette: {
      primary: { main: '#FF0000' } 
    }
  }
};

2. Full Override (disableDefaultTheme: true)

When disableDefaultTheme: true is provided, the built-in theme is completely disabled.
Only your custom styles are applied.

Best for:
Creating a fully unique design from scratch.

Example: Full redesign

const config: PublicConfig = {
  integrator: 'my-app',
  chains: [1, 56],
  disableDefaultTheme: true,
  theme: {
    shape: { borderRadius: 0 },
    container: { border: 'none' }
  }
};