react-button-catalog

v1.0.0

Published

4 days ago

Librería de botones React + TailwindCSS con 18 estilos, totalmente customizable e iconos de cualquier librería.

0High
0Medium
0Low

seedcodesv

react button tailwindcss ui components design-system

react-button-catalog

Librería de botones React + Tailwind CSS v4 con 18 estilos, 4 tamaños, totalmente customizable y con soporte de íconos de cualquier librería.

Creada a partir del catálogo de botones “Lumina Interface” (estilos Material 3, Glassmorphism, Neumorphic, Brutalista, Gótico, Futurista, Neón, Cartoon, Material/Google, Fluent/Microsoft, Pixel Art, Minecraft, Anime y Cyberpunk).

✨ Características

🎨 18 variantes × múltiples paletas de color por variante (25+ looks).
🔤 4 tamaños (sm, md, lg, xl) con tokens de tipografía propios.
🧩 Íconos de cualquier librería: lucide-react, react-icons, Material Symbols, emojis, SVGs… cualquier ReactNode funciona (icon, trailingIcon, iconOnly).
🌙 Dark mode por clase (dark en <html>), incluido en los estilos.
⏳ Estado de carga con spinner (customizable).
🔗 Polimórfico: renderiza <button>, <a>, <Link> de Next.js, etc. (as).
📐 fullWidth, redondeo configurable (rounded), className y style para overrides totales.
♿ Accesible: focus rings visibles, aria-disabled, estados disabled correctos.
📦 Cero configuración: importa un CSS compilado o usa el theme como preset de Tailwind v4.

📦 Instalación

npm install react-button-catalog
# o
pnpm add react-button-catalog
# o
yarn add react-button-catalog

Requiere react >= 18 y tailwindcss solo si quieres la integración con tu propio build de Tailwind (opción B). La opción A no requiere Tailwind.

🚀 Quickstart

Opción A — Sin configuración (importa el CSS compilado)

Importa el CSS de la librería una sola vez (en tu entry point) y listo:

import { Button } from "react-button-catalog";
import "react-button-catalog/styles.css"; // CSS compilado (incluye fuentes + tokens + dark mode)

export function App() {
  return (
    <div>
      <Button variant="primary" icon={<Rocket />}>Primary Action</Button>
      <Button variant="gradient" color="sunset">Sunset Glow</Button>
      <Button variant="neon" color="lime" rounded="md">LIME GLOW</Button>
    </div>
  );
}

Opción B — Con tu propio build de Tailwind v4 (recomendado para apps Tailwind)

En tu archivo CSS principal:

@import "tailwindcss";
@import "react-button-catalog/theme.css";   /* tokens de diseño */
@source "../node_modules/react-button-catalog/dist"; /* escanea las utilities del componente */

Así Tailwind genera solo las utilities que uses (tree-shaking real) y puedes sobrescribir los tokens desde tu propio @theme.

⚠️ Importa una sola de las dos opciones (A o B), nunca ambas.

🎨 Las 18 variantes

type ButtonVariant =
  | "primary" | "outline" | "ghost"        // Base (Material 3)
  | "glass"                                 // iOS / Glassmorphism
  | "gradient"                              // Degradados
  | "neumorphic"                            // Skeuomorphic
  | "brutalist"                             // Retro / Brutalista
  | "minimalist"                            // Minimalista
  | "gothic"                                // Gótico
  | "futuristic"                            // Futurista
  | "neon"                                  // Neón
  | "cartoon"                               // Cartoon
  | "material"                              // Google (Material 3)
  | "fluent"                                // Microsoft (Fluent)
  | "pixel"                                 // Pixel Art
  | "minecraft"                             // Minecraft
  | "anime"                                 // Anime
  | "cyberpunk";                            // Cyberpunk

Paletas por variante (prop `color`)

| Variante | Colores disponibles | | ------------- | ---------------------------------------------------- | | primary | default | | outline | default | | ghost | default | | glass | default, primary | | gradient | ocean, sunset, aurora | | neumorphic | soft, pill | | brutalist | yellow, orange, white | | minimalist | gray, border, soft | | gothic | crimson, veil, obsidian | | futuristic | system, link, cmd | | neon | lime, pink, cyan | | cartoon | pow, bam, zap | | material | google, tonal, outline | | fluent | primary, standard, subtle | | pixel | default | | minecraft | default | | anime | default | | cyberpunk | access, glitch |

<Button variant="gradient" color="aurora">Aurora</Button>
<Button variant="cartoon" color="bam">BAM</Button>
<Button variant="cyberpunk" color="access">Access</Button>

Cada variante tiene un redondeo por defecto; sobrescríbelo con rounded.

🧩 Íconos de cualquier librería

icon, trailingIcon e iconOnly aceptan cualquier ReactNode. Por eso puedes usar cualquier librería de íconos:

// lucide-react
import { Rocket, Heart, ArrowRight } from "lucide-react";
<Button icon={<Rocket />} trailingIcon={<ArrowRight />}>Go</Button>

// react-icons (Font Awesome / Material / etc.)
import { FaRocket } from "react-icons/fa";
<Button icon={<FaRocket />}>Launch</Button>

// Material Symbols (fuente)
<Button icon={<span className="material-symbols-outlined">rocket_launch</span>}>Launch</Button>

// Emojis
<Button icon="🚀">Launch</Button>

// SVG inline
<Button icon={<svg viewBox="0 0 24 24" fill="currentColor"><path d="..." /></svg>}>Launch</Button>

Los íconos se escalan automáticamente al tamaño del botón (SVGs con size-full).

<Button iconOnly icon={<Search />} aria-label="Buscar" />  // botón cuadrado solo ícono
<Button icon={<Heart />}>Leading</Button>                   // ícono inicial
<Button trailingIcon={<ArrowRight />}>Trailing</Button>     // ícono final

⚙️ API de props

| Prop | Tipo | Default | Descripción | | --------------- | --------------------------- | ------------- | ------------------------------------------------------------------ | | variant | ButtonVariant | "primary" | Familia de estilo (las 18). | | color | string | "default" | Paleta dentro de la variante. | | size | "sm" \| "md" \| "lg" \| "xl" | "md" | Tamaño del botón. | | rounded | "none" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "full" | según variante | Redondeo de esquinas. | | icon | ReactNode | — | Ícono inicial. | | trailingIcon | ReactNode | — | Ícono final. | | iconOnly | boolean | false | Botón cuadrado solo ícono. | | loading | boolean | false | Muestra spinner y desactiva. | | spinner | ReactNode | — | Spinner personalizado. | | fullWidth | boolean | false | width: 100%. | | as | ElementType | "button" | Renderiza como a, Link, etc. | | className | string | — | Clases extra (overrides). | | style | CSSProperties | — | Estilos inline. | | disabled, type, onClick, aria-*, data-*… | hereda de <button> | | |

<Button
  variant="outline"
  size="lg"
  rounded="full"
  icon={<Mail />}
  loading={sending}
  fullWidth
>
  Enviar mensaje
</Button>

🔧 Customización

1. `className` — anula cualquier clase

<Button className="!bg-emerald-500 hover:!bg-emerald-600 text-white shadow-lg">
  Verde personalizado
</Button>

2. `style` — estilos inline

<Button style={{ background: "linear-gradient(135deg, #f97316, #db2777)", color: "#fff" }}>
  Gradiente inline
</Button>

3. Tokens de tema — cambia toda la librería (Tailwind v4)

Con la Opción B, sobrescribe los tokens en tu @theme:

@import "tailwindcss";
@import "react-button-catalog/theme.css";

@theme {
  --color-primary: #7c3aed;      /* cambia el azul primario a violeta */
  --radius-btn-md: 0.75rem;      /* esquinas más redondeadas */
  --spacing-btn-px-md: 1.25rem;  /* más padding horizontal */
}

Tokens disponibles: --color-* (paleta Material 3 completa), --font-button-*, --text-button-*, --radius-btn-* y --spacing-btn-*.

4. Tema oscuro

Añade/remueve la clase dark en el elemento raíz:

document.documentElement.classList.toggle("dark", enabled);

Los estilos base (primary, outline, ghost, glass, minimalist, …) incluyen variantes dark: ya configuradas.

🔗 Renderizado polimórfico (`as`)

// Como <a>
<Button as="a" href="/docs" variant="gradient">Documentación</Button>

// Como Link de Next.js
import Link from "next/link";
<Button as={Link} href="/dashboard">Dashboard</Button>

// Como <button> nativo (por defecto)
<Button onClick={handleClick}>Guardar</Button>

Los props del elemento destino (href, target, etc.) se infieren en TypeScript.

⏳ Estados: loading y disabled

<Button loading>Enviando…</Button>            {/* spinner por defecto */}
<Button loading spinner={<CustomSpinner />}>Cargando</Button>
<Button disabled>No disponible</Button>

🚀 Next.js / SSR / Vite

Next.js (App Router): el componente es 100% cliente-compatible. Úsalo directamente en componentes clientes ("use client" si lo necesitas).
Vite / Remix / Astro: compatible sin configuración extra; importa el CSS en tu entry point.
El paquete publica ESM + CJS + .d.ts (tipos incluidos).

🧑‍💻 Desarrollo de la librería

npm install        # instala dependencias
npm run dev        # demo en vivo (localhost:5173)
npm run build      # compila la librería → dist/ (JS, CJS, CSS, d.ts)
npm run build:demo # compila el sitio demo estático → demo-dist/
npm run typecheck  # chequeo de tipos

Estructura

src/
├── index.ts          # entry point de la librería (exports públicos)
├── Button.tsx        # componente <Button>
├── buttonStyles.ts   # mapas de estilos: 18 variantes × colores, tamaños, radios
├── types.ts          # tipos públicos (ButtonProps, ButtonVariant, …)
├── theme.css         # tokens de diseño (shipped como react-button-catalog/theme.css)
├── index.css         # CSS de la librería (compilado a styles.css)
└── demo/             # página demo (Vite)

📄 Documentación adicional

docs/VARIANTS.md — catálogo visual completo de variantes y paletas.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

react-button-catalog

✨ Características

📦 Instalación

🚀 Quickstart

Opción A — Sin configuración (importa el CSS compilado)

Opción B — Con tu propio build de Tailwind v4 (recomendado para apps Tailwind)

🎨 Las 18 variantes

Paletas por variante (prop color)

🧩 Íconos de cualquier librería

⚙️ API de props

🔧 Customización

1. className — anula cualquier clase

2. style — estilos inline

3. Tokens de tema — cambia toda la librería (Tailwind v4)

4. Tema oscuro

🔗 Renderizado polimórfico (as)

⏳ Estados: loading y disabled

🚀 Next.js / SSR / Vite

🧑‍💻 Desarrollo de la librería

Estructura

📄 Documentación adicional

📝 Licencia

Paletas por variante (prop `color`)

1. `className` — anula cualquier clase

2. `style` — estilos inline

🔗 Renderizado polimórfico (`as`)