Starknet Tokenkit

A drop-in token selector for Starknet dApps. Themeable, keyboard-navigable, and built to slot into wallets, DEXes, and any UI that needs a tokens picker.

• Live playground: https://cycle-stark.github.io/starknet-tokenkit-package/
• Docs: https://docs.tokenkithq.io/docs/sdk/installation
• Marketing site / list a token: https://tokenkithq.io

Tested with React 19 and Next.js.

---

Install

pnpm add starknet-tokenkit styled-components
# or
npm i starknet-tokenkit styled-components

react, react-dom, and styled-components are peer dependencies.

Quick start

import { useState } from 'react';
import {
  TokenKitWrapper,
  SelectTokenModal,
  themes,
  type IToken,
} from 'starknet-tokenkit';

export default function App() {
  const [selected, setSelected] = useState<IToken | null>(null);

  return (
    <TokenKitWrapper
      network="SN_MAIN"
      apiKey="YOUR_API_KEY"
      mainnetEndpoint="https://api.tokenkithq.io"
      sepoliaEndpoint="https://api.sepolia.tokenkithq.io"
      themeObject={themes.dark}
      options={{ tokensToLoad: 'public', enableRecent: true }}
    >
      <SelectTokenModal
        selectedToken={selected}
        callBackFunc={setSelected}
        modalWidth="420px"
        modalHeight="90dvh"
      >
        <button>Select Token</button>
      </SelectTokenModal>
    </TokenKitWrapper>
  );
}

The children of SelectTokenModal is your trigger element. Click it to open the modal.

Components

Component	Purpose
TokenKitWrapper	Top-level provider. Wraps TokenKitProvider + ThemeProvider. Configure once, near the root.
SelectTokenModal	Native <dialog>-based modal that wraps SelectTokenContainer. Use this if you want the click-to-open trigger pattern.
SelectTokenContainer	Inline (non-modal) version of the selector. Render it directly inside your own layout.
TokenLogo	Shared logo component. Falls back to initials if logo is empty or the image fails to load.

Options (TokenKitOptions)

Passed to TokenKitWrapper via the options prop.

Option	Type	Default	Behavior
tokensToLoad	'public' | 'all'	'public'	Which token set to load from the API.
enableRecent	boolean	false	Opt in to persisting and displaying a "Recent" tokens section. When false, nothing is read from or written to localStorage.

Modal props (SelectTokenModal, SelectTokenContainer)

Prop	Type	Notes
selectedToken	IToken | null | undefined	Currently selected token (controlled).
callBackFunc	(token: IToken) => void	Called when a token is picked.
modalWidth	string	Optional. Defaults to 420px. Auto-shrinks on mobile.
modalHeight	string	Optional. Defaults to theme height (e.g. 60dvh).

Theming

The package ships several presets you can use as-is or fork.

import { themes, type Theme } from 'starknet-tokenkit';

// Use a preset
<TokenKitWrapper themeObject={themes.lavender} ...>

// Or define your own
const myTheme: Theme = {
  colors: {
    textColor: '#f5f5f5',
    headerFooterBg: '#2c2c2c',
    background: '#1a1a1a',
    primaryColor: '#646cff',
    searchBackground: '#2c2c2c',
    searchColor: '#f5f5f5',
    searchBorderColor: '#444444',
    searchFocusBorderColor: '#646cff',
    placeholderColor: '#888888',
  },
  fonts: { fontFamily: "'Inter', sans-serif" },
  borderRadius: 20,
  height: '60dvh',
};

Available presets: dark, light, blue, gradient, sunset, ocean, monochrome, emerald, lavender, ember, frost, carbon, candy.

The fonts.fontFamily is honored across all elements (including native form controls — <input>, <button> — which normally ignore inherited font-family).

Keyboard

• ↑ / ↓ — move focus through results
• Enter — select the focused token
• Esc — close the modal

Development

pnpm install
pnpm dev                # playground at http://localhost:5173
pnpm run build:package  # build the library to dist/ (tsup)
pnpm run build:pages    # build the playground SPA to dist-pages/
pnpm run preview:pages  # preview the SPA build locally

Two Vite configs live in the repo:

• vite.config.ts — library mode (used by pnpm build)
• vite.config.pages.ts — SPA mode for the playground (used by pnpm build:pages and the Pages workflow)

Releasing

Bump the version in package.json, push, then create a GitHub release. The npm-publish.yml workflow runs npm run build && npm publish on release creation.

License

MIT