Skip to content

docs: clean up widget pages and document widget-react #642

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
raq0x wants to merge 1 commit into
base: main
Choose a base branch
from
+51 −38
Open

docs: clean up widget pages and document widget-react #642

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 6 additions & 25 deletions docs/cow-protocol/integrate/widget.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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

Expand Down
58 changes: 45 additions & 13 deletions docs/cow-protocol/tutorials/widget/widget.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
Expand All @@ -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 <CowSwapWidget params={params} onReady={() => 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
Expand All @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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:
Expand All @@ -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, // <-------
})
```
Expand Down Expand Up @@ -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,
}

Expand All @@ -428,7 +459,7 @@ Try it yourself: <https://widget.cow.fi>.

## 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)
Expand Down Expand Up @@ -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',
Expand Down Expand Up @@ -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 = [
Expand All @@ -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
Expand Down
Loading