O que solanaui faz?
Uma biblioteca de componentes React focada em Solana, construída sobre shadcn/ui, Radix UI e Tailwind CSS. Todos os componentes são apresentacionais – eles aceitam dados via props e emitem callbacks. Não possuem dependências de blockchain, adaptadores de wallet ou importações de SDK. Você os conecta à sua própria camada de dados.
Quando Usar
Use os componentes SolanaUI ao construir interfaces de aplicativos Solana. Os componentes cuidam da camada de UI – renderizando ícones de tokens, formatando preços, exibindo tabelas e gráficos – enquanto seu código gerencia a busca de dados, conexões de wallet e lógica de transações.
Integração típica: busque dados da sua API ou fonte on-chain, transforme-os para corresponder à interface de props do componente e passe-os. Conecte-se aos callbacks (onSubmit, onSelect, onValueChange) para acionar sua lógica de aplicação.
Instalação
Requer que o shadcn/ui esteja inicializado no seu projeto (components.json deve existir). Se não, execute pnpm dlx shadcn@latest init primeiro.
Adicione o registro SolanaUI ao seu components.json:
{
"registries": {
"@solanaui": "https://solanaui.dev/r/{name}.json"
}
}
Em seguida, instale os componentes:
pnpm dlx shadcn@latest add @solanaui/swap-box
Quaisquer primitivas shadcn/ui necessárias (Card, Dialog, Button, etc.) são resolvidas automaticamente como dependências do registro. Os componentes também dependem do utilitário cn() de @/lib/utils.
Convenções de Importação
import { SwapBox } from "@/components/sol/swap-box";
import { PoolTable } from "@/components/sol/pool-table";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Button } from "@/components/ui/button";
Padrões de Integração
Conectando a Fontes de Dados
Os componentes aceitam dados simples via props. Mapeie seus dados para as formas das props:
// Sua fonte de dados (API, on-chain, gerenciamento de estado, etc.)
const positions = usePositions(); // seu hook
// Mapeie para a forma da prop do componente
<PositionTable
positions={positions.map(p => ({
symbol: p.market.baseSymbol,
icon: p.market.baseIconUrl, // use suas próprias URLs de ícone
side: p.direction,
size: formatNumber(p.size),
value: formatUsd(p.notionalValue),
leverage: `${p.leverage}x`,
entryPrice: formatUsd(p.entryPrice),
markPrice: formatUsd(p.currentPrice),
pnl: formatPnl(p.unrealizedPnl),
pnlPercent: formatPercent(p.unrealizedPnlPercent),
pnlTrend: p.unrealizedPnl >= 0 ? "up" : "down",
}))}
onClosePosition={(pos) => closePosition(pos.symbol)}
onEditTpSl={(pos, values) => updateTpSl(pos.symbol, values)}
/>
Ícones de Token
Os componentes aceitam URLs de ícone como strings. Use qualquer fonte de ícone que seu projeto já tenha – seu próprio CDN, registro de tokens ou serviço de metadados.
Se você precisar de ícones de placeholder para prototipagem, estas URLs públicas de CDN funcionam:
- SOL:
https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png - USDC:
https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png - BONK:
https://arweave.net/hQiPZOsRZXGXBJd_82PhVdlM_hACsT_q6wqwf5cSY7I - JitoSOL:
https://storage.googleapis.com/token-metadata/JitoSOL-256.png - mSOL:
https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/mSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So/logo.png
Manipulando Callbacks
Os componentes emitem callbacks para ações do usuário. Conecte-os à sua lógica de aplicação:
<SwapBox
tokens={availableTokens}
defaultFromToken="USDC"
defaultToToken="SOL"
fromBalance={wallet.usdcBalance}
details={quoteDetails}
submitLabel="Swap"
// Sua lógica de execução de swap
onSubmit={() => executeSwap(fromToken, toToken, amount)}
/>
<ActionBox
tokens={supportedTokens}
label="Stake"
balance={wallet.solBalance}
details={stakingDetails}
submitLabel="Stake SOL"
onSubmit={() => submitStakeTransaction(selectedToken, amount)}
/>
Catálogo de Componentes (30 componentes)
ActionBox (action-box)
Formulário de ação de entrada única para staking, empréstimo, depósito em LP, bridging. A contraparte versátil do TradeBox.
interface ActionBoxProps {
tokens: { icon: string; symbol: string }[];
defaultToken?: string;
balance?: string;
label?: string;
details?: { label: string; value: string; className?: string }[];
submitLabel?: string;
onSubmit?: () => void;
className?: string;
}
ActivityFeed (activity-feed)
Lista cronológica de atividades com ícones, timestamps (objetos Date) e valores. Usa date-fns formatDistanceToNow para tempo relativo.
interface ActivityFeedProps {
items: { icon?: string; title: string; description?: string; timestamp: Date; value?: string }[];
className?: string;
}
AddressDisplay (address-display)
Endereço Solana truncado com cópia para área de transferência e link opcional para explorador. explorerUrl é uma URL base; o endereço é anexado automaticamente.
interface AddressDisplayProps {
address: string; truncate?: boolean; truncateChars?: [number, number];
copyable?: boolean; explorerUrl?: string; className?: string;
}
AuthCard (auth-card)
Cartão de login com entrada de email opcional, botões de login social e botões de provedor de wallet.
interface AuthCardProps {
title?: string; description?: string; showEmail?: boolean;
socialProviders?: { name: string; icon: React.ReactNode }[];
walletProviders?: { name: string; icon: React.ReactNode }[];
}
HealthBar (health-bar)
Barra de progresso gradiente (vermelho para verde) com valor percentual colorido.
interface HealthBarProps { value: number; label?: string; showValue?: boolean; className?: string }
LeverageSlider (leverage-slider)
Slider para selecionar alavancagem de negociação com botões de atalho min/máx.
interface LeverageSliderProps {
min?: number; max?: number; step?: number; value?: number[];
defaultValue?: number[]; onValueChange?: (value: number[]) => void; className?: string;
}
NFTCard (nft-card)
Cartão exibindo imagem, nome, coleção e preço do NFT com estados de carregamento/erro.
interface NFTCardProps {
name: string; image: string; collection?: string;
price?: string; currency?: string; className?: string;
}
OrderBook (order-book)
Livro de ordens de negociação com níveis de oferta/demanda, tamanhos, totais acumulados, spread, preço médio e barras de profundidade.
interface OrderBookProps {
bids: { price: number; size: number }[];
asks: { price: number; size: number }[];
className?: string;
}
OrderForm (order-form)
Formulário de ordens TP/SL para posições abertas. Entradas duplas de TP (preço + % de ganho), entradas duplas de SL (preço + % de perda). Passe entryPrice para sincronizar automaticamente entre campos de preço e percentual.
interface OrderFormProps {
title?: string; description?: string; entryPrice?: number;
details?: { label: string; value: string; className?: string }[];
onSubmit?: (values: { tpPrice: string; tpPercent: string; slPrice: string; slPercent: string }) => void;
className?: string;
}
PoolCard (pool-card)
Cartão versátil para pools de token único ou múltiplo. Mostra ícones empilhados, preço opcional, descrição, grade de métricas, gráfico sparkline e slot para filhos.
interface PoolCardProps {
tokens: { icon: string; symbol: string }[]; name?: string; price?: string; description?: string;
metrics?: { label: string; value: string; highlight?: boolean; className?: string }[];
series?: { time: string; value: number }[]; children?: React.ReactNode; className?: string;
}
PoolTable (pool-table)
Tabela de dados com ícones de token (um ou mais por linha), colunas definidas pelo usuário, ordenável e ações de linha opcionais. Funciona para listagens de pool, tabelas de token, tabelas de validadores.
interface PoolTableProps {
columns: { key: string; label: string; className?: string }[];
rows: { icons: { src: string; alt?: string }[]; name?: string; data: Record<string, string> }[];
actions?: React.ReactNode[]; className?: string;
}
PositionCard (position-card)
Cartão mostrando uma posição DeFi com ícone de token, valor, valor em USD, APY e rodapé de ação opcional.
interface PositionCardProps {
symbol: string; icon: string; amount: string; value: string;
apy?: string; trend?: "up" | "down"; children?: React.ReactNode; className?: string;
}
PositionTable (position-table)
Tabela de posições de negociação abertas com tipo (long/short), ícone do ativo, tamanho, alavancagem, preços de entrada/marcação e P&L colorido. Colunas de ação TP/SL editável e Fechar incorporadas com UIs de diálogo.
interface PositionTablePosition {
symbol: string; icon: string; side: "long" | "short";
size: string; value: string; leverage: string;
entryPrice: string; markPrice: string; liquidationPrice?: string;
pnl: string; pnlPercent?: string; pnlTrend?: "up" | "down";
}
interface PositionTableProps {
positions: PositionTablePosition[];
onEditTpSl?: (position: PositionTablePosition, values: { tpPrice: string; tpPercent: string; slPrice: string; slPercent: string }) => void;
onClosePosition?: (position: PositionTablePosition) => void;
className?: string;
}
PriceChart (price-chart)
Gráfico de área para histórico de preço de token ou valor de portfólio com eixos, grade, preenchimento gradiente e tooltips.
interface PriceChartProps {
title?: string; description?: string;
series: { time: string; value: number }[]; className?: string;
}
SparklineChart (sparkline-chart)
Sparkline inline mínimo com coloração automática positiva/negativa e rótulo de variação percentual.
interface SparklineChartProps { series: { time: string; value: number }[]; className?: string }
StatCard (stat-card)
Cartão de exibição de estatísticas com rótulo, valor, ícone opcional e badge de tendência opcional.
interface StatCardProps {
label: string; value: string; change?: string;
trend?: "up" | "down"; icon?: React.ReactNode; className?: string;
}
SwapBox (swap-box)
Formulário de swap de token de dois lados com botão de inversão, linhas de detalhes e ação de envio. O botão de inversão troca os tokens selecionados no lugar (os rótulos permanecem fixos).
interface SwapBoxProps {
tokens: { icon: string; symbol: string }[];
defaultFromToken?: string; defaultToToken?: string;
fromBalance?: string; toBalance?: string; fromLabel?: string; toLabel?: string;
details?: { label: string; value: string; className?: string }[];
submitLabel?: string; onSubmit?: () => void; className?: string;
}
TokenCombobox (token-combobox)
Dropdown pesquisável para selecionar um token com ícones e seleção por checkmark.
interface TokenComboboxProps {
tokens: { icon: string; symbol: string }[];
defaultValue?: string; onSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
}
TokenCommand (token-command)
Diálogo de comando Cmd+K para pesquisar e selecionar tokens. Passe tokens (lista plana) ou groups (seccionados), não ambos.
type TokenCommandProps = {
onSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
} & (
| { tokens: { icon: string; symbol: string }[]; groups?: never }
| { groups: { heading: string; tokens: { icon: string; symbol: string }[] }[]; tokens?: never }
)
TokenIcon (token-icon)
Imagem de ícone de token circular com skeleton de carregamento e fallback de erro.
type TokenIconProps = { src: string; alt: string; width?: number; height?: number; className?: string }
TokenIconGroup (token-icon-group)
Ícones de token sobrepostos empilhados para pares LP ou grupos de múltiplos tokens. Mostra badge +N quando excede o máximo.
interface TokenIconGroupProps {
tokens: { src: string; alt?: string }[]; size?: number; overlap?: number; max?: number; className?: string;
}
TokenInput (token-input)
Entrada numérica com seletor de token integrado, saldo da wallet, botões Half/Max e exibição de valor em USD. Formata com separadores de milhar. onValueChange recebe a string bruta não formatada.
interface TokenInputProps {
tokens: { icon: string; symbol: string }[]; defaultToken?: string; balance?: string;
value?: string; usdValue?: string; onValueChange?: (value: string) => void;
onTokenSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
}
TradeBox (trade-box)
Formulário de negociação de perpétuos/margem com alternância long/short, entrada de token, slider de alavancagem, linhas de detalhes e envio. Para ações não comerciais, use ActionBox.
interface TradeBoxProps {
tokens: { icon: string; symbol: string }[]; defaultToken?: string; balance?: string;
labels?: [string, string]; defaultSide?: string;
leverageMin?: number; leverageMax?: number; leverageDefault?: number; leverageStep?: number;
details?: { label: string; value: string; className?: string }[];
submitLabel?: string; onSubmit?: () => void; className?: string;
}
TradeButtons (trade-buttons)
Grupo de alternância para selecionar direção de negociação (Long/Short ou Buy/Sell) com estados codificados por cor.
interface TradeButtonsProps {
defaultValue?: string; value?: string; onValueChange?: (value: string) => void;
labels?: [string, string]; className?: string;
}
TradeChart (trade-chart)
Gráfico de velas alimentado por TradingView lightweight-charts com suporte a tema claro/escuro.
interface TradeChartProps {
data: { time: string | number; open: number; high: number; low: number; close: number }[];
visibleBars?: number; className?: string;
}
TrendBadge (trend-badge)
Badge pequeno colorido com ícone de tendência para mudanças positivas (verde) ou negativas (vermelho).
interface TrendBadgeProps { trend?: "up" | "down"; children: React.ReactNode; className?: string }
TxnTable (txn-table)
Tabela de transações com links de assinatura truncados, timestamps relativos (objetos Date, via date-fns), badges de ação e quantidades de tokens.
interface TxnTableProps {
transactions: {
signature: string; timestamp: Date; action: string; token: string;
tokenIcon?: string; amount: string; value?: string; explorerUrl?: string;
}[];
className?: string;
}
VolumeChart (volume-chart)
Gráfico de barras para volume histórico de negociação com eixos, grade e tooltips. Dados de série temporal única com valores numéricos.
interface VolumeChartProps {
title?: string; description?: string;
series: { time: string; value: number }[]; className?: string;
}
WalletBalance (wallet-balance)
Cartão de saldo da wallet com ícone de token, saldo, valor em USD e botão de recarga.
interface WalletBalanceProps {
icon: string; symbol: string; balance: string; value?: string;
onRefresh?: () => void; className?: string;
}
Temas e Personalização
Os componentes herdam o tema global do shadcn/ui via CSS custom properties (variáveis CSS) definidas no seu globals.css. Para modificar o tema, edite essas variáveis -- os componentes as respeitam automaticamente.
Componentes de Grade
Para posicionar uniformemente os cartões de pool e ícones de token na sua página, use Tailwind:
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
{pools.map(pool => <PoolCard key={pool.id} {...pool} />)}
</div>
Compatibilidade
- Funciona com qualquer framework React (Next.js, Remix, Vite, etc.)
- Íntegro com shadcn/ui e Radix UI
- Funciona com qualquer solução de conexão Solana (Wallet Standard, Backpack, Phantom, Solflare, etc.)
- Agnóstico de dados e estado
- Pronto para TypeScript