@vulcx/widget

Embeddable swap widget for the Vulcx DEX aggregator. Framework-agnostic Web Component that works in React, Vue, Svelte, Angular, or plain HTML.

Install

npm install @vulcx/widget

Or via CDN (no build step needed):

<script src="https://cdn.vulcx.xyz/vulcx-widget.umd.js"></script>

Usage

HTML / CDN

<script src="https://cdn.vulcx.xyz/vulcx-widget.umd.js"></script>

<vulcx-swap
  api-key="vulcx_your_api_key"
  default-input-mint="So11111111111111111111111111111111111111112"
  default-output-mint="uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG"
  theme="dark"
></vulcx-swap>

React

import "@vulcx/widget";

function App() {
  return (
    <vulcx-swap
      api-key="vulcx_your_api_key"
      default-input-mint="So11111111111111111111111111111111111111112"
      default-output-mint="uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG"
      theme="dark"
    />
  );
}

For TypeScript, add to your global.d.ts:

declare namespace JSX {
  interface IntrinsicElements {
    "vulcx-swap": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        "api-key"?: string;
        "default-input-mint"?: string;
        "default-output-mint"?: string;
        theme?: "dark" | "light";
      },
      HTMLElement
    >;
  }
}

Vue

<template>
  <vulcx-swap
    api-key="vulcx_your_api_key"
    default-input-mint="So11111111111111111111111111111111111111112"
    default-output-mint="uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG"
    theme="dark"
    @quote-update="onQuote"
    @swap-complete="onSwap"
  />
</template>

<script setup>
import "@vulcx/widget";

function onQuote(e) {
  console.log("Quote:", e.detail);
}
function onSwap(e) {
  console.log("Swap:", e.detail);
}
</script>

Next.js

"use client";
import { useEffect, useRef } from "react";

export default function SwapWidget() {
  const ref = useRef<HTMLElement>(null);

  useEffect(() => {
    import("@vulcx/widget");
  }, []);

  return (
    <vulcx-swap
      ref={ref}
      api-key="vulcx_your_api_key"
      theme="dark"
    />
  );
}

Attributes

| Attribute | Type | Default | Description | | --------------------- | ------------------ | ---------- | ------------------------------ | | api-key | string | — | Required. Your API key | | base-url | string | Production | API base URL override | | default-input-mint | string | — | Pre-selected input token mint | | default-output-mint | string | — | Pre-selected output token mint | | theme | "dark"\|"light" | "dark" | Color theme |

Events

| Event | Detail | Description | | ----------------- | ----------------------------------------- | ----------------------------- | | quote-update | QuoteResponse | Fired when a new quote loads | | swap-initiated | { inputMint, outputMint, amount } | Fired when swap starts | | swap-complete | SwapResponse | Fired on successful swap | | swap-error | { error: string } | Fired on swap failure | | connect-wallet | {} | Fired when user clicks swap without wallet |

Wallet Integration

Set the wallet address programmatically:

const widget = document.querySelector("vulcx-swap");
widget.setWallet("9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM");

Listen for the connect-wallet event to trigger your wallet adapter:

widget.addEventListener("connect-wallet", async () => {
  const wallet = await connectWallet(); // your wallet adapter
  widget.setWallet(wallet.publicKey.toString());
});

Customization

Override CSS custom properties on the host element:

vulcx-swap {
  --vulcx-bg: #0d0d12;
  --vulcx-accent: #00ff88;
  --vulcx-radius: 20px;
}

Available CSS variables:

| Variable | Default (dark) | Description | | --------------------------- | -------------- | ------------------ | | --vulcx-bg | #0a0a0f | Background | | --vulcx-surface | #141419 | Card/panel bg | | --vulcx-surface-hover | #1c1c24 | Hover state | | --vulcx-border | #2a2a35 | Borders | | --vulcx-text | #e8e8ed | Primary text | | --vulcx-text-secondary | #8b8b9a | Secondary text | | --vulcx-accent | #c8ff00 | Accent / CTA | | --vulcx-error | #ff4d6a | Error color | | --vulcx-radius | 16px | Border radius |