From 871cb3d5c7c72540d206152c991cfd70a81158de Mon Sep 17 00:00:00 2001 From: raq0x Date: Thu, 9 Jul 2026 11:24:35 +0200 Subject: [PATCH] docs: clean up widget pages and document widget-react --- docs/cow-protocol/integrate/widget.mdx | 31 ++--------- docs/cow-protocol/tutorials/widget/widget.md | 58 +++++++++++++++----- 2 files changed, 51 insertions(+), 38 deletions(-) diff --git a/docs/cow-protocol/integrate/widget.mdx b/docs/cow-protocol/integrate/widget.mdx index bb0053332..0b6ec064e 100644 --- a/docs/cow-protocol/integrate/widget.mdx +++ b/docs/cow-protocol/integrate/widget.mdx @@ -4,7 +4,7 @@ The CoW Widget is the fastest way to integrate CoW Protocol's trading functional ## Overview -The CoW Widget is a ready-to-use React component that provides the full CoW Swap trading experience. It's perfect for projects that want to add trading functionality quickly without building a custom interface from scratch. +The CoW Widget is a ready-to-use component that provides the full CoW Swap trading experience. It's perfect for projects that want to add trading functionality quickly without building a custom interface from scratch. ## Key Features @@ -25,8 +25,8 @@ const widgetContainer = document.getElementById('cowswap-widget') const params: CowSwapWidgetParams = { appCode: 'YOUR-APP-NAME', // Required: identifies your app - width: 600, - height: 640, + width: '600px', + height: '640px', sell: { asset: 'USDC' }, buy: { asset: 'WETH', amount: '0.1' }, theme: 'light', // 'light' | 'dark' | custom theme object @@ -46,6 +46,8 @@ createCowSwapWidget(widgetContainer, { params }) npm install @cowprotocol/widget-lib ``` +Building with React? Use [`@cowprotocol/widget-react`](https://www.npmjs.com/package/@cowprotocol/widget-react) instead - it wraps the widget as a React component. + ## Configuration Options The widget supports extensive customization: @@ -56,28 +58,7 @@ The widget supports extensive customization: - **Token lists**: Use custom token lists - **Wallet integration**: Connect to your app's wallet or standalone mode - **Event handling**: Listen to trading events and notifications - -## Example with Custom Theme - -```typescript -import { createCowSwapWidget, CowSwapWidgetPalette } from '@cowprotocol/widget-lib' - -const customTheme: CowSwapWidgetPalette = { - baseTheme: 'light', - primary: '#00ff85', - background: '#f7f7f7', - paper: '#1a4435', - text: '#ffffff', -} - -const params = { - appCode: 'YOUR-APP-NAME', - theme: customTheme, - // ... other params -} - -createCowSwapWidget(widgetContainer, { params }) -``` +- **And more**: Slippage limits, token pair constraints, custom sounds and images ## When to Use the Widget diff --git a/docs/cow-protocol/tutorials/widget/widget.md b/docs/cow-protocol/tutorials/widget/widget.md index d880ba7d7..d92bf827f 100644 --- a/docs/cow-protocol/tutorials/widget/widget.md +++ b/docs/cow-protocol/tutorials/widget/widget.md @@ -31,7 +31,7 @@ import { createCowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-li const widgetContainer = document.getElementById('cowswap-widget') const params: CowSwapWidgetParams = { - appCode: 'NAME-OF-YOU-APP', // Add here the name of your app. e.g. "Pig Swap" + appCode: 'NAME-OF-YOUR-APP', // Add here the name of your app. e.g. "Pig Swap" width: '600px', height: '640px', sell: { asset: 'DAI' }, @@ -41,17 +41,46 @@ const params: CowSwapWidgetParams = { createCowSwapWidget(widgetContainer, { params }) ``` +## React + +If your app is built with React, use the [`@cowprotocol/widget-react`](https://www.npmjs.com/package/@cowprotocol/widget-react) wrapper instead. It renders the same widget as a React component and accepts the same `CowSwapWidgetParams`: + +```bash +yarn add @cowprotocol/widget-react +``` + +```bash +npm install @cowprotocol/widget-react +``` + +```tsx +import { CowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-react' + +const params: CowSwapWidgetParams = { + appCode: 'NAME-OF-YOUR-APP', // Add here the name of your app. e.g. "Pig Swap" + width: '600px', + height: '700px', + tradeType: 'swap', +} + +function App() { + return console.log('Widget ready')} /> +} +``` + +All configuration described in the rest of this guide applies to the React component as well. + ## App key You must specify the `appCode` parameter when initializing the widget. This parameter is used to identify the source of orders. The key must be a UTF8 string of up to 50 chars. It will be a part of orders meta-data, see more in -the [CoW Protocol Docs](https://docs.cow.fi/front-end/creating-app-ids/create-the-order-meta-data-file/appcode). +the [app data docs](/cow-protocol/reference/core/intents/app-data). ## Partner fee -You may participate in the Partner Fee program to collect fee on [Market order](https://docs.cow.fi/cow-protocol/concepts/order-types/market-orders) trades executed by your users through the Widget by +You may participate in the Partner Fee program to collect fee on [Market order](/cow-protocol/concepts/order-types/market-orders) trades executed by your users through the Widget by adding the following parameter to your Widget: ```typescript @@ -75,7 +104,7 @@ This configuration will apply a partner fee for all networks and trade types (sw Both `bps` and `recipient` can be set for different chains and different trade types (swap/limit/advanced). -Bellow you can see the `partnerFee` configuration variations: +Below you can see the `partnerFee` configuration variations: ```typescript import { PartnerFee, SupportedChainId, TradeType } from '@cowprotocol/widget-lib' @@ -154,6 +183,8 @@ For example, you can define different fees for different assets: ```typescript import { createCowSwapWidget, CowSwapWidgetParams, CowEventListeners, CowEvents } from '@cowprotocol/widget-lib' +const container = document.getElementById('cowswap-widget') + let updateParams = null const recipient = '0x0000000000000000000000000000000000000000' @@ -304,7 +335,7 @@ Paste the snippet into **RAW JSON params** → open the **Swap** form → check ## Wallet provider You can pass the wallet provider from your application to seamlessly use the widget as part of your application. -Also, you can not specify the provider, in this case the widget will work in standalone mode with the ability to connect +Alternatively, you can omit the provider, in this case the widget will work in standalone mode, letting users connect any wallet supported in CoW Swap. A provider must comply with [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) and implement the interface: @@ -331,7 +362,7 @@ An example of connecting a widget to Rabby Wallet or Metamask: import { createCowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-lib' createCowSwapWidget(document.getElementById('cowswap-widget'), { - params: { appCode: 'NAME-OF-YOU-APP' }, // Add here the name of your app. e.g. "Pig Swap" + params: { appCode: 'NAME-OF-YOUR-APP' }, // Add here the name of your app. e.g. "Pig Swap" provider: window.ethereum, // <------- }) ``` @@ -415,7 +446,7 @@ const theme: CowSwapWidgetPalette = { success: '#19ff64', } const params: CowSwapWidgetParams = { - appCode: 'NAME-OF-YOU-APP', // Add here the name of your app. e.g. "Pig Swap" + appCode: 'NAME-OF-YOUR-APP', // Add here the name of your app. e.g. "Pig Swap" theme, } @@ -428,7 +459,7 @@ Try it yourself: . ## Custom tokens -CowSwap uses the [token lists standard](https://tokenlists.org), which allows flexible and decentralized management of assets for trading. +CoW Swap uses the [token lists standard](https://tokenlists.org), which allows flexible and decentralized management of assets for trading. You can manage the list of tokens in CoW Swap UI: ![Tokens management](/img/tutorials/widget-tokens-management.png) @@ -463,7 +494,7 @@ import { createCowSwapWidget, CowSwapWidgetParams, TokenInfo } from '@cowprotoco const container = document.getElementById('cowswap-widget') -const customTokens: TokenInfo = [ +const customTokens: TokenInfo[] = [ { chainId: 1, address: '0x69D29F1b0cC37d8d3B61583c99Ad0ab926142069', @@ -534,6 +565,8 @@ To avoid double display of notifications, enable the `disableToastMessages` opti ```typescript import { createCowSwapWidget, CowSwapWidgetParams, CowEventListeners, CowEvents } from '@cowprotocol/widget-lib' +const container = document.getElementById('cowswap-widget') + const params: CowSwapWidgetParams = { appCode: 'YOUR_APP_ID' } const listeners: CowEventListeners = [ @@ -559,14 +592,13 @@ import { createCowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-li const container = document.getElementById('cowswap-widget') const params: CowSwapWidgetParams = { - appCode: 'NAME-OF-YOU-APP', // Add here the name of your app. e.g. "Pig Swap" - logoUrl: 'YOUR_LOGO_URL', + appCode: 'NAME-OF-YOUR-APP', // Add here the name of your app. e.g. "Pig Swap" } -const updateWidget = createCowSwapWidget(container, { params }) +const { updateParams } = createCowSwapWidget(container, { params }) // Update the widget -updateWidget({ +updateParams({ ...params, theme: 'dark', // <- Change theme to dark hideNetworkSelector: true, // <- Hide the network selector