@uidex/button

Token-driven, interaction-aware Button component for React + Tailwind CSS.

Built for expressive UI (bevel, glow, parallax, neon effects) while staying fully customizable via CSS tokens.

✨ Features

• Token-based color system (CSS variables)
• Multiple built-in variants (default, destructive, neon)
• Fully custom color support
• Scale + Parallax interactions
• Optional scroll-up text animation
• Icon support (left or right)
• Touch-safe hover via mouse-hover variant
• No external CSS frameworks bundled
• Works with React 18+

📦 Install

npm install @uidex/button

Peer Dependencies

(Required in your project)

• react >= 18
• react-dom >= 18
• tailwindcss >= 3

⚙️ Tailwind Setup (IMPORTANT)

UIDEX relies on Tailwind utilities and a small custom variant (mouse-hover).

In your main Tailwind CSS file (e.g., src/index.css):

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Import UIDEX mouse-hover variant */
@import "@uidex/button/styles.css";

[!CAUTION] UIDEX does NOT bundle Tailwind. Your project must already process Tailwind CSS.

🚀 Basic Usage

import { Button } from "@uidex/button";

function App() {
  return <Button>Click Me</Button>;
}

🧩 Props API

| Prop | Type | Default / Options | | :------------- | :---------- | :----------------------------- | ------------- | ---------- | -------- | | variant | string | default | destructive | neon | custom | | size | string | sm | md | lg | | interaction | string | none | scale | parallax | | animation | string | none | scroll-up | | state | string | default | active | | icon | ReactNode | Optional React node | | iconPosition | string | left | right | | customColors | object | Required if variant="custom" | | className | string | Extra Tailwind classes | | type | string | button | submit | reset |

🎨 Variants

Variants define color tokens only.

Default (Blue)

<Button variant="default">Default</Button>

Destructive (Red)

<Button variant="destructive">Delete</Button>

Neon (Cyber Glow)

<Button variant="neon" interaction="parallax">
  Neon Mode
</Button>

Custom Variant

You control all colors via CSS variables.

<Button
  variant="custom"
  interaction="parallax"
  customColors={{
    bg: "#111827",
    text: "#ffffff",
    hoverText: "#000000",
    glow: "#7c3aed",
    borderTop: "#a78bfa",
    borderRight: "#0b1220",
    borderBottom: "#0b1220",
    borderLeft: "#a78bfa",
  }}
>
  Custom Button
</Button>

customColors Shape

All properties are optional (fallbacks provided).

{
  bg: string,
  text: string,
  hoverText: string,
  glow: string,
  borderTop: string,
  borderRight: string,
  borderBottom: string,
  borderLeft: string
}

🖱 Interactions

Scale Interaction

Small hover + active scale effect.

<Button interaction="scale">Hover Me</Button>

Parallax Interaction (3D Bevel Effect)

Inset glow + border flip on hover. Best used with neon or strong custom themes.

<Button variant="neon" interaction="parallax">
  Parallax
</Button>

🔁 Scroll-Up Animation

Text flips upward on hover. Works with icons too.

<Button animation="scroll-up">Services</Button>

🔥 Active State (For Navigation / Toggles)

Adds aria-pressed automatically.

<Button state={isActive ? "active" : "default"}>Dashboard</Button>

🎯 Icons

Accepts any React node.

import { Menu, ArrowRight } from "lucide-react";

/* Left Icon (default) */
<Button icon={<Menu />}>
  Menu
</Button>

/* Right Icon */
<Button icon={<ArrowRight />} iconPosition="right">
  Continue
</Button>

📏 Sizes

<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

♿ Accessibility

• Uses native <button> element.
• Supports standard type attribute.
• Uses aria-pressed when state="active".
• Includes focus-visible ring styles.
• Hover effects disabled on touch devices via mouse-hover media query.

🧠 How It Works

UIDEX uses CSS variables internally:

• --btn-bg
• --btn-text
• --btn-hover-text
• --btn-glow
• --btn-border-top / right / bottom / left

Variants define these tokens, and interactions consume them. This architecture makes the system fully themeable, interaction-safe, and easy to extend.

📦 Package Info

• Tree-shakeable
• ESM + CJS support
• No Tailwind bundled (Prevents version conflicts)
• No heavy runtime styling libraries

🛠 Troubleshooting

Hover not working on mobile? This is expected behavior. UIDEX disables hover on touch devices to avoid "sticky" hover states.

Styles not applied? Make sure:

1. Tailwind is configured properly in your project.
2. You imported @uidex/button/styles.css.
3. Your Tailwind config is processing the node_modules CSS if necessary.

🛣 Roadmap

Planned packages:

• @uidex/input
• @uidex/card
• @uidex/modal
• @uidex/tabs

📄 License

MIT

💎 Brand

npm install @uidex/button