¿Qué hace solanaui?
Una biblioteca de componentes React enfocada en Solana, construida sobre shadcn/ui, Radix UI y Tailwind CSS. Todos los componentes son presentacionales: aceptan datos a través de props y emiten callbacks. No tienen dependencias de blockchain, adaptadores de wallet ni imports de SDK. Tú los conectas a tu propia capa de datos.
Cuándo usar
Usa los componentes de SolanaUI al construir interfaces de aplicaciones Solana. Los componentes manejan la capa de UI — renderizar íconos de tokens, formatear precios, mostrar tablas y gráficos — mientras que tu código se encarga de la obtención de datos, conexiones de wallet y lógica de transacciones.
Integración típica: obtén datos de tu API o fuente on-chain, transformalos para que coincidan con la interfaz de props del componente, pásalos. Conecta callbacks (onSubmit, onSelect, onValueChange) para activar tu lógica de aplicación.
Instalación
Requiere que shadcn/ui esté inicializado en tu proyecto (debe existir components.json). Si no, ejecuta primero pnpm dlx shadcn@latest init.
Agrega el registro de SolanaUI a tu components.json:
{
"registries": {
"@solanaui": "https://solanaui.dev/r/{name}.json"
}
}
Luego instala componentes:
pnpm dlx shadcn@latest add @solanaui/swap-box
Cualquier primitiva necesaria de shadcn/ui (Card, Dialog, Button, etc.) se resuelve automáticamente como dependencia del registro. Los componentes también dependen de la utilidad cn() de @/lib/utils.
Convenciones de importación
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";
Patrones de integración
Conexión a fuentes de datos
Los componentes aceptan datos planos a través de props. Mapea tus datos a las formas de las props:
// Tu fuente de datos (API, on-chain, gestión de estado, etc.)
const positions = usePositions(); // tu hook
// Mapea a la forma de prop del componente
<PositionTable
positions={positions.map(p => ({
symbol: p.market.baseSymbol,
icon: p.market.baseIconUrl, // usa tus propias URL de íconos
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)}
/>
Íconos de tokens
Los componentes aceptan URL de íconos como cadenas de texto. Usa cualquier fuente de íconos que tu proyecto ya tenga: tu propio CDN, registro de tokens o servicio de metadatos.
Si necesitas íconos de marcador de posición para prototipado, estas URL públicas de CDN funcionan:
- 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
Manejo de callbacks
Los componentes emiten callbacks para acciones del usuario. Conéctalos a tu lógica de aplicación:
<SwapBox
tokens={availableTokens}
defaultFromToken="USDC"
defaultToToken="SOL"
fromBalance={wallet.usdcBalance}
details={quoteDetails}
submitLabel="Swap"
// Tu lógica de ejecución de intercambio
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)
Formulario de acción de una sola entrada para staking, préstamos, depósito en LP, puentes. La contraparte versátil de 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 de actividades cronológica con íconos, marcas de tiempo (objetos Date) y valores. Usa date-fns formatDistanceToNow para tiempo relativo.
interface ActivityFeedProps {
items: { icon?: string; title: string; description?: string; timestamp: Date; value?: string }[];
className?: string;
}
AddressDisplay (address-display)
Dirección Solana truncada con copia al portapapeles y enlace opcional al explorador. explorerUrl es una URL base; la dirección se agrega automáticamente.
interface AddressDisplayProps {
address: string; truncate?: boolean; truncateChars?: [number, number];
copyable?: boolean; explorerUrl?: string; className?: string;
}
AuthCard (auth-card)
Tarjeta de inicio de sesión con entrada de correo electrónico opcional, botones de inicio de sesión social y botones de proveedores 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 progreso degradada (rojo a verde) con valor porcentual coloreado.
interface HealthBarProps { value: number; label?: string; showValue?: boolean; className?: string }
LeverageSlider (leverage-slider)
Control deslizante para seleccionar apalancamiento de trading con botones de acceso directo para mínimo/máximo.
interface LeverageSliderProps {
min?: number; max?: number; step?: number; value?: number[];
defaultValue?: number[]; onValueChange?: (value: number[]) => void; className?: string;
}
NFTCard (nft-card)
Tarjeta que muestra imagen NFT, nombre, colección y precio con estados de carga/error.
interface NFTCardProps {
name: string; image: string; collection?: string;
price?: string; currency?: string; className?: string;
}
OrderBook (order-book)
Libro de órdenes de trading con niveles de compra/venta, tamaños, totales acumulados, diferencial, precio medio y barras de profundidad.
interface OrderBookProps {
bids: { price: number; size: number }[];
asks: { price: number; size: number }[];
className?: string;
}
OrderForm (order-form)
Formulario de órdenes TP/SL para posiciones abiertas. Entradas duales TP (precio + % de ganancia), entradas duales SL (precio + % de pérdida). Pasa entryPrice para sincronización automática entre campos de precio y porcentaje.
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)
Tarjeta versátil para pools de un solo token o múltiples tokens. Muestra íconos apilados, precio opcional, descripción, cuadrícula de métricas, gráfico de chispa y slot para hijos.
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)
Tabla de datos con íconos de token (uno o más por fila), columnas definidas por el usuario, ordenable y acciones de fila opcionales. Funciona para listados de pools, tablas de tokens, tablas 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)
Tarjeta que muestra una posición DeFi con ícono de token, cantidad, valor en USD, APY y pie de acción opcional.
interface PositionCardProps {
symbol: string; icon: string; amount: string; value: string;
apy?: string; trend?: "up" | "down"; children?: React.ReactNode; className?: string;
}
PositionTable (position-table)
Tabla de posiciones de trading abiertas con tipo (largo/corto), ícono del activo, tamaño, apalancamiento, precios de entrada/marca y P&L coloreado. Columnas de acción integradas de edición de TP/SL y Cerrar con interfaces 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 áreas para historial de precio de token o valor de cartera con ejes, cuadrícula, relleno degradado e información emergente.
interface PriceChartProps {
title?: string; description?: string;
series: { time: string; value: number }[]; className?: string;
}
SparklineChart (sparkline-chart)
Minigráfico de chispa mínimo con color automático positivo/negativo y etiqueta de cambio porcentual.
interface SparklineChartProps { series: { time: string; value: number }[]; className?: string }
StatCard (stat-card)
Tarjeta de visualización de estadísticas con etiqueta, valor, ícono opcional y badge de tendencia opcional.
interface StatCardProps {
label: string; value: string; change?: string;
trend?: "up" | "down"; icon?: React.ReactNode; className?: string;
}
SwapBox (swap-box)
Formulario de intercambio de dos lados con botón de voltear, filas de detalles y acción de envío. El botón de voltear intercambia los tokens seleccionados en el lugar (las etiquetas permanecen fijas).
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)
Menú desplegable con búsqueda para seleccionar un token con íconos y selección con marca de verificación.
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 buscar y seleccionar tokens. Pasa tokens (lista plana) o groups (seccionados), no 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)
Imagen de ícono de token circular con esqueleto de carga y fallback de error.
type TokenIconProps = { src: string; alt: string; width?: number; height?: number; className?: string }
TokenIconGroup (token-icon-group)
Íconos de token superpuestos apilados para pares LP o grupos de múltiples tokens. Muestra badge +N cuando excede el máximo.
interface TokenIconGroupProps {
tokens: { src: string; alt?: string }[]; size?: number; overlap?: number; max?: number; className?: string;
}
TokenInput (token-input)
Entrada numérica con selector de token integrado, saldo de wallet, botones Mitad/Máximo y visualización de valor en USD. Formatea con separadores de miles. onValueChange recibe la cadena sin formato.
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)
Formulario de trading de perpetuos/margen con alternancia largo/corto, entrada de token, control deslizante de apalancamiento, filas de detalles y envío. Para acciones que no son de trading, usa 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 alternancia para seleccionar dirección de trading (Largo/Corto o Comprar/Vender) con estados codificados por colores.
interface TradeButtonsProps {
defaultValue?: string; value?: string; onValueChange?: (value: string) => void;
labels?: [string, string]; className?: string;
}
TradeChart (trade-chart)
Gráfico de velas impulsado por TradingView lightweight-charts con soporte de tema oscuro/claro.
interface TradeChartProps {
data: { time: string | number; open: number; high: number; low: number; close: number }[];
visibleBars?: number; className?: string;
}
TrendBadge (trend-badge)
Badge pequeño coloreado con ícono de tendencia para cambios positivos (verde) o negativos (rojo).
interface TrendBadgeProps { trend?: "up" | "down"; children: React.ReactNode; className?: string }
TxnTable (txn-table)
Tabla de transacciones con enlaces de firma truncados, marcas de tiempo relativas (objetos Date, mediante date-fns), badges de acción y cantidades de token.
interface TxnTableProps {
transactions: {
signature: string; timestamp: Date; action: string; token: string;
tokenIcon?: string; amount: string; value?: string; explorerUrl?: string;
}[];
className?: string;