simplekit-react

Conjunto de componentes de interfaz para React, listos para usar con Tailwind CSS. Incluye botones, inputs, selects, cards, modales, sistema de toasts y utilidades de navegación, con tipados completos y build ESM/CJS + d.ts.

La librería está pensada para integrarse en proyectos que ya usan Tailwind. No incluye CSS propio; los componentes usan clases de Tailwind para estilado.

Instalación

Instala la librería (React 19+ requerido):

npm i simplekit-react
# o
yarn add simplekit-react
# o
pnpm add simplekit-react
# o
bun add simplekit-react

Peer dependencies (si tu proyecto ya usa React, seguramente ya las tienes):

• react >=19 <20
• react-dom >=19 <20
• framer-motion >=11 (solo si usas Modal, Drawer o Toasts)

Requisitos de estilos:

• Tailwind CSS v4 (o equivalente) configurado en tu proyecto, ya que los componentes están escritos con clases utilitarias.

Uso rápido

import React from "react";
import { ButtonUI, Card, CardHeader, CardTitle, CardContent } from "simplekit-react";

export default function Example() {
  return (
    <Card className="max-w-sm">
      <CardHeader>
        <CardTitle>Hola</CardTitle>
      </CardHeader>
      <CardContent>
        <ButtonUI color="primary">Acción</ButtonUI>
      </CardContent>
    </Card>
  );
}

Matriz de componentes (resumen)

| Categoría | Componentes destacados | | --- | --- | | Formularios | InputUI, TextareaUI, CheckboxUI, SelectUI, RadioGroup, Switch, NumberInput, DatePickerUI, DateRangePicker, TimePickerUI, FileUpload, TagInput, ColorPicker | | Feedback | Alert, ToastProvider, ToastContainer, Spinner, Skeleton, Progress, ConfirmDialog, Modal, Drawer | | Navegación | NavLinkUI, SidebarNavLink, Breadcrumbs, Pagination, Tabs, Menubar | | Superficie de datos | Card, Table, TableSelection, EmptyState, Metric | | Interacción avanzada | CommandPalette, ContextMenu, Popover, Tooltip, Carousel, ImageZoom, TransferList |

Íconos en SidebarNavLink

SidebarNavLink acepta icon?: ReactNode, así que puedes pasar cualquier ícono de cualquier librería:

import { SidebarNavLink } from "simplekit-react";
import { Home } from "lucide-react"; // ejemplo, pero puedes usar cualquier ReactNode

<SidebarNavLink href="/" label="Inicio" description="Ir a inicio" icon={<Home className="h-4 w-4" />} isOpen />;

Si prefieres FontAwesome:

import { SidebarNavLink } from "simplekit-react";
import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
import { faHouse } from "@fortawesome/free-solid-svg-icons";

<SidebarNavLink href="/" label="Inicio" icon={<FontAwesomeIcon icon={faHouse} />} isOpen />;

Sistema de Toasts

Envuelve tu app con el proveedor y monta el contenedor una sola vez:

import { ToastProvider, ToastContainer, useToast } from "simplekit-react";

function App() {
  return (
    <ToastProvider>
      <MyPage />
      <ToastContainer />
    </ToastProvider>
  );
}

function MyPage() {
  const { toast } = useToast();
  return (
    <button onClick={() => toast.success("Guardado", "Cambios aplicados")}>Mostrar toast</button>
  );
}

Formularios básicos

import { InputUI, SelectUI, SelectItem, TextareaUI, CheckboxUI } from "simplekit-react";

<InputUI label="Nombre" placeholder="Tu nombre" />
<SelectUI label="Opción">
  <SelectItem value="1">Uno</SelectItem>
  <SelectItem value="2">Dos</SelectItem>
</SelectUI>
<TextareaUI label="Mensaje" />
<CheckboxUI label="Acepto los términos" />

Integración con react-hook-form

La librería exporta helpers en simplekit-react/integrations para reducir boilerplate con Controller.

import { useForm } from "react-hook-form";
import { RHFInputField, RHFCheckboxField } from "simplekit-react";

type FormValues = {
  name: string;
  terms: boolean;
};

export function ExampleForm() {
  const { handleSubmit, control } = useForm<FormValues>({
    defaultValues: { name: "", terms: false },
  });

  return (
    <form onSubmit={handleSubmit(console.log)} className="space-y-4">
      <RHFInputField control={control} name="name" label="Nombre" />
      <RHFCheckboxField control={control} name="terms" label="Acepto los términos" />
      <button type="submit">Enviar</button>
    </form>
  );
}

Navegación (polimórfica)

NavLinkUI y SidebarNavLink renderizan un <a> por defecto, así que funcionan sin ninguna librería de routing:

import { NavLinkUI, SidebarNavLink } from "simplekit-react";
import { Home } from "lucide-react"; // Usa cualquier ícono como ReactNode

<NavLinkUI href="/" variant="modern">Inicio</NavLinkUI>
<SidebarNavLink href="/" label="Inicio" icon={<Home />} isOpen />

Si necesitas integrarlos con react-router, next/link, Gatsby u otro router basado en React, pasa el componente mediante la prop as y reutiliza las props (to, href, etc.) propias del router:

import { NavLink as RouterNavLink } from "react-router";
import { NavLinkUI } from "simplekit-react";

<NavLinkUI as={RouterNavLink} to="/" variant="modern">
  Inicio
</NavLinkUI>

Controla el estado activo con tu router (pasando isActive cuando tengas la información) o aplicando clases adicionales. NavLinkUI usa clases como nav-link, nav-link-secondary, etc. Ajusta esas clases en tu CSS o sustitúyelas por tus propios estilos. El resto de componentes usan utilidades de Tailwind directamente.

SSR y frameworks (Next.js/Remix)

• El paquete no inyecta CSS y no requiere runtime global para estilos.
• Componentes interactivos (por ejemplo Modal, Drawer, ToastContainer, CommandPalette) deben renderizarse en contexto cliente cuando el framework separa SSR/CSR.
• En Next.js App Router, usa "use client" en el archivo que renderiza componentes interactivos y providers.
• Evita acceder a APIs de navegador (window, document, localStorage) en tu código de servidor cuando compongas estos componentes.

Estilos y Tailwind

• Los componentes usan clases de Tailwind; el paquete no inyecta CSS.
• Asegúrate de tener Tailwind configurado en tu app y que tu pipeline procese clases dinámicas (por ejemplo bg-, text-, rounded-, etc.).
• Si deseas replicar los estilos del playground, puedes basarte en tus propios tokens/temas Tailwind.

Tailwind v4: declarar fuentes (@source)

Si usas Tailwind v4, añade en tu hoja de estilos global (por ejemplo src/index.css o src/app.css) las rutas desde donde Tailwind debe escanear clases. Incluye también este paquete para que sus clases se generen correctamente:

/* Dile a Tailwind v4 dónde escanear clases */
@source "./index.html";
@source "./src/**/*.{js,jsx,ts,tsx,html}";

/* Incluye la librería para que sus clases se generen */
@source "./node_modules/simplekit-react/dist/**/*.{js,cjs}";

Ajusta las rutas relativas según la ubicación de tu CSS global. Por ejemplo, si tu CSS vive en src/styles/globals.css, cambia los prefijos ./ por ../ donde sea necesario.

Tipos y tree‑shaking

• Exporta ESM (dist/index.js), CJS (dist/index.cjs) y tipos (dist/index.d.ts).
• sideEffects: false permite tree‑shaking.

Desarrollo local (playground)

Este repo incluye un playground con Vite para probar los componentes:

npm run dev      # inicia el playground
npm run build    # genera la librería en dist/

Licencia

Pendiente de definir por el autor.