Uniswap Widget and Embeddable Integration Versions

The widget follows a semantic versioning scheme with major, minor, and patch releases. Major versions introduce breaking changes to the configuration API or React component interface.

Third-party sites embedding the widget via the @uniswap/widgets npm package.

Pin to a specific major version in package.json. Test all configuration parameters and callback handlers before adopting a new major release.

Major version bumps can alter the structure of the configuration object (e.g., tokens, theme, convenienceFee, routerUrl). Unrecognized parameters may be silently ignored or cause initialization failures.

Frontend developers and protocol integrators who pass custom configuration to the widget.

Review the widget's changelog and migration guide for each major release. Audit your configuration object against the new schema to prevent silent misconfiguration.

The widget bundles a default token list. Updates to this list can add or remove tokens from the default selector, affecting asset discoverability for users.

Integrators who do not supply a custom token list via the tokenList configuration parameter.

Explicitly define a custom token list if your application requires a stable set of assets. Monitor the widget's release notes for default list changes that could remove tokens your users expect.

The widget's internal routing logic and the default quote API endpoint can change between versions. A new version may use a different routing algorithm or API schema.

Any site where swap execution quality is critical, including DeFi dashboards and wallets.

Verify that the widget version you are using points to your intended routing infrastructure. If using a custom routerUrl, confirm compatibility with the new widget version's quote consumption logic.

Running an end-of-life widget version means missing security patches for the swap interface, Permit2 integration, or transaction construction. Users are exposed to known bugs.

All integrators who do not have a widget upgrade monitoring process.

Establish a recurring task to check the widget's GitHub releases and npm package for new versions. Treat a lagging major version as a security and operational risk.

The theme object's structure can change, breaking custom branding. New required fields may be added, or existing fields may be renamed or deprecated.

Integrators who apply a custom theme to match their application's design system.

Test your theme object against each new major version in a staging environment. Look for console warnings about deprecated theme parameters.

The signature and behavior of callback functions (e.g., onTxSubmit, onTxSuccess, onTxFail) can change. A new version may alter the data payload or the timing of callbacks.

Wallets and applications that use widget callbacks to trigger custom post-swap logic or analytics events.

Review the callback type definitions in the new version's documentation. Update your handler functions to match the new signatures and test the full transaction lifecycle.

Integrator pins to a deprecated major version (e.g., v2) that no longer receives security patches or bug fixes.

Critical

Third-party websites, DeFi dashboards, NFT marketplaces

Implement automated version monitoring against the canonical npm registry. Migrate to the latest stable major version immediately.

A minor or patch release introduces a new required prop or changes the behavior of an existing configuration parameter without a major version bump.

High

All embedders using programmatic configuration

Pin to exact minor and patch versions in package.json. Review the changelog for every update before deployment. Use automated integration tests that validate widget rendering and swap quote generation.

The embedded widget's default routing behavior (e.g., Auto Router vs. UniswapX toggle) changes due to a front-end release, altering execution quality for users without explicit integrator action.

Medium

Wallets, portfolio trackers, aggregator front-ends

Explicitly set the routerPreference parameter in the widget configuration rather than relying on defaults. Monitor the Uniswap Web Interface Release Notes for changes that could affect the underlying API.

The widget relies on a cached or outdated default token list, causing users to interact with unverified tokens or miss newly listed assets.

Medium

Integrators who do not supply a custom token list

Supply a curated, integrator-controlled token list via the tokenList prop. If using the default list, ensure the widget version is recent enough to fetch the latest list from the Uniswap Labs CDN.

A widget update changes the Permit2 integration flow, causing signature failures for wallets that have not updated their EIP-712 domain handling.

High

Wallets with custom Permit2 signature implementations

Test the full Permit2 signature and gasless approval flow in a staging environment against every new widget release. Verify domain separator and witness type string compatibility.

The widget generates UniswapX orders with parameters (e.g., decay function, exclusive filler) that are incompatible with the active Reactor contract deployment on a specific chain.

High

Integrators enabling UniswapX on L2s or alternative chains

Verify the Reactor contract address and version on each target chain. Do not enable UniswapX features on chains without a confirmed, compatible Reactor deployment.

A compromised or malicious update to a transitive dependency of the widget package introduces a supply-chain attack that exfiltrates user swap parameters or private keys.

Critical

All embedders

Use a lockfile with integrity hashes. Audit the widget's dependency tree for unexpected changes. Integrate the widget within an isolated execution context (e.g., an iframe with a strict Content Security Policy).