Yield.xyz Widget Pro

Widget Pro is a ready-to-deploy reference app built on top of the Yield.xyz Widget. Where the Widget is the installable React/JS package you embed in your own product, Widget Pro is a complete, hostable front end that wraps the Widget and pre-configures it for a richer, dashboard-style experience.

Use Widget Pro when you want a standalone, branded yield app you can deploy as-is (or fork and tweak) — instead of integrating the Widget component into an existing codebase.

📘

Widget vs. Widget Pro

• Widget (@stakekit/widget) — the core package that is installable and integrated into different projects.
• Widget Pro — a deployment that adds the Widget as a dependency and displays it with additional configuration options (dashboard layout, institutional wallets, curated validators, theming, and analytics) wired up out of the box.

What's included

Widget Pro is a Vite + React application that renders the SKApp component from @stakekit/widget with an opinionated configuration:

• Dashboard layout via dashboardVariant — shows positions and details rather than the compact single-flow widget.
• Institutional wallet support via institutionalWallets.
• Curated validators — only preferred validators are shown across all chains.
• Enabled-yields-only token list so users only see tokens with available opportunities.
• Custom light & dark themes built on top of the Widget's lightTheme / darkTheme.
• Analytics through Mixpanel using the Widget's tracking hooks.
• Help & support section built from the Widget's HelpModal components.

Prerequisites

• An API key from Yield.xyz (used as VITE_API_KEY).
• A Mixpanel project token if you want analytics (used as VITE_MIX_PANEL_TOKEN).
• The project toolchain managed by mise and pnpm.

Getting started

1. Install the toolchain and dependencies

mise install
pnpm install

2. Configure environment variables

Create a local environment file and set the required public Vite variables:

cp .env.example .env

# .env
VITE_API_KEY=your-api-key
VITE_MIX_PANEL_TOKEN=your-mixpanel-token

📘

Note

Both variables are public (VITE_-prefixed) and are bundled into the client build. VITE_MIX_PANEL_TOKEN is optional — if it is omitted, analytics tracking is simply disabled.

3. Run the development app

pnpm dev

Open http://localhost:3002 in your browser.

4. Build and preview for production

pnpm build
pnpm start

The preview server also runs on http://localhost:3002.

Code quality

pnpm lint     # Biome checks + TypeScript type checking
pnpm format   # Apply Biome autofixes

How the Widget is configured

Widget Pro mounts the Widget in src/app/widget/widget.tsx. This is the single place where the Pro behavior is defined:

import "@stakekit/widget/style.css";
import { SKApp } from "@stakekit/widget";
import { config } from "../../config";
import { tracking } from "../tracking";
import { widgetProLightTheme } from "./themes";

export const Widget = () => {
  return (
    <SKApp
      apiKey={config.apiKey}
      theme={widgetProLightTheme}
      tracking={tracking}
      dashboardVariant
      variant="utila"
      institutionalWallets
      tokensForEnabledYieldsOnly
      validatorsConfig={{
        "*": {
          preferredOnly: true,
        },
      }}
    />
  );
};

Configuration options

These are the Widget props that Widget Pro sets. All of them are standard SKApp props, so you can adjust or remove any of them to change the experience.

📘

Note

For the full list of available SKApp props (such as yieldId, hideNetworkLogo, language, externalProviders, tokenIconMapping, chainIconMapping, hideChainSelector, and more), see the Widget documentation.

validatorsConfig reference

validatorsConfig?: {
  [Key in SupportedSKChains | "*"]?: {
    allowed?: string[];
    blocked?: string[];
    preferred?: string[];
    mergePreferredWithDefault?: boolean;
    preferredOnly?: boolean;
  };
};

Use the "*" key to apply a config to every chain, or a specific chain key to target one network.

Theming

Widget Pro ships custom light and dark themes in src/app/widget/themes.ts. They are created by deep-merging overrides onto the Widget's exported lightTheme / darkTheme, so you only specify the values you want to change:

import { darkTheme, lightTheme } from "@stakekit/widget";
import merge from "lodash.merge";

export const widgetProLightTheme = merge(structuredClone(lightTheme), {
  space: { buttonMinHeight: "40px" },
  borderRadius: {
    baseContract: { primaryButton: "8px" },
  },
  color: {
    backgroundMuted: "#f5f5f6",
    stakeSectionBackground: "#f5f5f6",
    primaryButtonBackground: "#4A60FF",
    primaryButtonColor: "#FFFFFF",
    // ...
  },
});

A matching widgetProDarkTheme is also provided. To switch the active theme, pass the desired theme object to the theme prop in src/app/widget/widget.tsx. You can also pass both modes ({ lightMode, darkMode }) and let the Widget follow the user's color-scheme preference.

For the complete list of themeable tokens (colors, fonts, spacing, border radii, z-indices, etc.), see the Theme properties section of the Widget documentation.

Analytics

Tracking is wired up in src/app/tracking.ts. When VITE_MIX_PANEL_TOKEN is set, Mixpanel is initialized and the Widget's tracking hooks forward events and page views to it:

import type { SKAppProps } from "@stakekit/widget";
import mixpanel from "mixpanel-browser";
import { config } from "../config";

export const mixpanelEnabled =
  typeof window !== "undefined" && config.mixPanelToken;

if (mixpanelEnabled) {
  mixpanel.init(config.mixPanelToken);
}

export const tracking: SKAppProps["tracking"] = mixpanelEnabled
  ? {
      trackEvent: (...args) => mixpanel.track(...args),
      trackPageView: (page, props) =>
        mixpanel.track_pageview({ page, ...(props && { props }) }),
    }
  : undefined;

If the token is not provided, tracking is undefined and no analytics are sent.

Help & support

The landing page renders a help/support section (src/app/widget/help-modals.tsx) using the Widget's HelpModal and TrackingContextProvider exports — for example "What is Yield.xyz?" and "Need help or have questions?" dialogs. These reuse the same tracking configuration so support interactions are captured alongside widget events.

Live example