Liquidswap Widget

A web component custom element that can be embedded in any frontend application, or even plain HTML/JS/CSS. Using the full strength of the SDK, the widget can provide swap operations from any other custom dApp, wallet, etc.


yarn add @pontem/liquidswap-widget


npm install @pontem/liquidswap-widget


Function loadWidget accepts widget HTML tag name as string. It can be custom name but must be in kebab case. We recommend to use liquidswap-widget name. Passed name must be exactly the same as tag name.

  • React

    import React, { useLayoutEffect } from 'react';
    import { loadWidget } from '@pontem/liquidswap-widget';
    export const Widget = () => {
      useLayoutEffect(() => {
      }, []);
      return (
        <div className="'Your Wrapper className'">
  • Vue

      <div class="'Your Wrapper class name'">
    <script setup lang="ts">
      import { loadWidget } from '@pontem/liquidswap-widget';
  • Any other framework / lib

    1. Make sure you added html tag liquidswap-widget into app.

    1. Import loadWidget function from npm and run with passing html tag name in kebab case;

    import { loadWidget } from '@pontem/liquidswap-widget';loadWidget('liquidswap-widget');

When Loaded

You can listen widget and add some logic (if necessary) when widget is embedded:

// customElements defined at global window object. 
customElements.whenDefined('liquidswap-widget').then(() => {
     // here custom logic

Live Example

Widget example published to github pages:

Liquidswap Widget as Dapp (native wallet application)

Liquidswap Widget could be used as Dapp inside wallet.

In that case web-custom-element needs several properties:

  • Account address of wallet;

const dataAccount = '0x15fd61229f6e12b51adbff45b7b74310c7eaf9c24ef8c13b653c8f2a07bc1d14';
  • Network information: name and chainId;

const dataNetwork = { name: 'mainnet', chainId: '1' };
  • Transaction info: status and hash;

interface ITransactionStatus {
  status: 'pending' | 'success' | 'error' | 'rejected';
  hash: string | null
const transactionStatus: ITransactionStatus = { status: 'pending', hash: null };
  • Properties should be passed as strings (data-attributes), so to pass Object variable you need to use JSON.stringify() on passing Object.

  • Properties will be extruded with JSON.parse() inside widget;

  • Properties are reactive, so any change to props will update widget’s internal store;

Also, widget will dispatch to Custom Events:

  1. signAndSubmitTransaction’ - this event will return CustomEvent with ‘detail’ property containing ready for wallet transaction payload. Just accept props inside handler and you will find prop ‘detail’ with full transaction payload;

  2. transactionProcessed’ - this event will be fired after widget accepts hash and status of transaction and correctly resolves it with.

Example in React-JSX
import React, { useLayoutEffect, useRef, useState } from 'react';
import { loadWidget } from '@pontem/liquidswap-widget';

export const Widget = () => {
  const [dataNetwork, setDataNetwork] = useState(
    { name: 'mainnet', chainId: '1' }
  const [dataAccount, setDataAccount] = useState(
  const [transactionStatus, setTransactionStatus] = useState<{ 
    status: string,
    hash: string | null
  }>({ status: 'pending', hash: null });
  const ref = useRef();
  const transactionHandler = (props: CustomEvent) => {
    // props.detail will be contain payload. 
  const processedHandler = (event: CustomEvent) => {
    // this event will be fired when user close modal with transaction status
    // neither it's success or error. After that point we do not need to 
    // provide hash or status. So it should be set to initial State: 
    setTransactionStatus({ status: 'pending', hash: null });
  useLayoutEffect(() => {
    // customElements available as window.customElements 
    customElements.whenDefined('liquidswap-widget').then(() => {
      if (ref.current) {
        const nodeElement = ref.current as unknown as Element;
  }, []);
  return (

Note: When this properties are passed to widget - it treats Parent element as ‘wallet environment’, so connect / disconnect wallet flow will be skipped / hidden.

Last updated