Interactive Button Component Library – React 3D Button

Description:

React 3D Button is a web button component that creates customizable buttons with interactive 3D press effects for React applications.

It handles complex interaction states like 3D press effects, ripple animations, and mobile touch events natively.

The package supports Next.js App Router, TypeScript, and CSS variable customization to fit specific design requirements.

Features

• 🎨 Six Pre-Built Themes: Ocean, Sunset, Forest, Pirate, Neon, and Default color schemes with scoped or global application
• 📐 Granular Size Control: Six size options from xs to 2xl with backward-compatible legacy sizing
• 🔘 Border Radius Variants: Configure corner radius from sharp edges to pill-shaped buttons
• 📏 Full Width Mode: Buttons expand to container width when enabled
• ⏳ Loading States: Built-in spinner with optional loading text during async operations
• 🎭 CSS Variable Customization: Override theme variables without modifying component code
• 📱 Mobile Touch Support: Optimized touch event handling for mobile devices
• ⚡ Next.js Compatibility: Functions with Next.js 13+ and App Router architecture
• 🎯 TypeScript Definitions: Complete type exports with JSDoc annotations
• 🎪 3D Press Effects: Transform-based depth animations with hover tilt and ripple options
• 🔘 Toggle Mode: Persistent pressed states with controlled and uncontrolled patterns
• ♿ Accessibility Support: ARIA attributes and keyboard navigation included
• 📦 Tree-Shakeable Builds: ESM and CJS formats for optimal bundle optimization
• 🎨 Nine Button Variants: Primary, Secondary, Tertiary, Success, Error, Warning, Info, Anchor, Danger
• 🔄 Zero Dependencies: Pure React implementation with no external runtime requirements

Use Cases

• Landing Pages and Marketing Sites: Interactive CTAs with visual depth effects for conversion-focused interfaces
• SaaS Dashboards: Action buttons with semantic color coding for admin panels and data views
• E-commerce Checkout Flows: Loading states and full-width buttons for payment and confirmation steps
• Form Submissions: Toggle buttons for settings panels and boolean controls in configuration interfaces

How to Use It

Installation

1. Install the package through npm, yarn, or pnpm:

npm install react-3d-button

2. Import the Button3D component and base stylesheet in your React file:

import { Button3D } from 'react-3d-button';
import 'react-3d-button/styles';
function App() {
  return (
    <Button3D type="primary" onPress={() => console.log('Pressed!')}>
      Click Me
    </Button3D>
  );
}

3. For Next.js applications, add the ‘use client’ directive at the top of your component file:

'use client';
import { Button3D } from 'react-3d-button';
import 'react-3d-button/styles';
export default function MyComponent() {
  return (
    <Button3D type="primary" onPress={() => alert('Hello!')}>
      Press Me
    </Button3D>
  );
}

Applying Themes

The library supports two theme application patterns. Global themes affect all Button3D instances in your application. Import the .global.css variant to apply a theme globally:

import { Button3D } from 'react-3d-button';
import 'react-3d-button/styles';
import 'react-3d-button/themes/pirate.global.css';
function App() {
  return (
    <>
      <Button3D type="primary">Pirate Button</Button3D>
      <Button3D type="success">Also Pirate</Button3D>
    </>
  );
}

Scoped themes target specific sections through wrapper classes. Import the standard .css theme file and wrap buttons in the corresponding theme class:

import { Button3D } from 'react-3d-button';
import 'react-3d-button/styles';
import 'react-3d-button/themes/ocean.css';
import 'react-3d-button/themes/sunset.css';
function App() {
  return (
    <>
      <div className="theme-ocean">
        <Button3D type="primary">Ocean Button</Button3D>
      </div>
      <div className="theme-sunset">
        <Button3D type="primary">Sunset Button</Button3D>
      </div>
    </>
  );
}

The available themes include Ocean (cool blues and teals), Sunset (warm oranges and purples), Forest (earthy greens and browns), Pirate (rich browns and tans), and Neon (vibrant neon colors). Each theme provides both global and scoped import paths.

Creating Custom Themes

Override CSS variables to build custom themes. Target the .aws-btn class and define your color values:

.aws-btn {
  --button-primary-color: #10b981;
  --button-primary-color-dark: #059669;
  --button-primary-color-light: #ffffff;
  --button-primary-color-hover: #0d9668;
  --button-raise-level: 8px;
  --button-hover-pressure: 3;
}

Button Variants and Sizes

Access nine semantic button types through the type prop:

<Button3D type="primary">Primary</Button3D>
<Button3D type="secondary">Secondary</Button3D>
<Button3D type="success">Success</Button3D>
<Button3D type="error">Error</Button3D>
<Button3D type="warning">Warning</Button3D>

Configure button height through six size options:

<Button3D size="xs">Extra Small</Button3D>   {/* 24px height */}
<Button3D size="sm">Small</Button3D>          {/* 32px height */}
<Button3D size="md">Medium</Button3D>         {/* 40px height */}
<Button3D size="lg">Large</Button3D>          {/* 48px height */}
<Button3D size="xl">Extra Large</Button3D>    {/* 56px height */}
<Button3D size="2xl">2X Large</Button3D>      {/* 64px height */}

Border Radius Configuration

Control corner rounding through the rounded prop:

<Button3D rounded="none">No Radius</Button3D>    {/* 0px */}
<Button3D rounded="sm">Small</Button3D>          {/* 4px */}
<Button3D rounded="md">Medium</Button3D>         {/* 6px */}
<Button3D rounded="lg">Large</Button3D>          {/* 12px */}
<Button3D rounded="xl">Extra Large</Button3D>    {/* 16px */}
<Button3D rounded="full">Pill Shape</Button3D>   {/* 9999px */}

Loading States

Enable loading spinners through the loading prop. Add loadingText to display a message alongside the spinner:

const [isLoading, setIsLoading] = useState(false);
<Button3D
  loading={isLoading}
  loadingText="Processing..."
  onPress={async () => {
    setIsLoading(true);
    await submitForm();
    setIsLoading(false);
  }}
>
  Submit
</Button3D>

Icons and Custom Content

Insert icons through the before and after props:

import { ArrowRight, Download } from 'lucide-react';
<Button3D type="primary" before={<Download size={16} />}>
  Download
</Button3D>
<Button3D type="primary" after={<ArrowRight size={16} />}>
  Next
</Button3D>

The iconOnly prop creates square buttons optimized for icon display:

<Button3D iconOnly size="md">
  <PlusIcon />
</Button3D>
<Button3D iconOnly rounded="full" type="success">
  <CheckIcon />
</Button3D>

Toggle Mode

Enable persistent pressed states through the toggle prop. Use uncontrolled mode with defaultActive for internal state management:

<Button3D
  type="success"
  toggle
  defaultActive={false}
  onChange={(active) => console.log('Toggle state:', active)}
>
  Click to Toggle
</Button3D>

Control toggle state externally through the active prop:

const [isEnabled, setIsEnabled] = useState(false);
<Button3D
  type="primary"
  toggle
  active={isEnabled}
  onChange={setIsEnabled}
>
  {isEnabled ? '✓ Enabled' : 'Disabled'}
</Button3D>

Rendering as Links

Pass an href prop to render the button as an anchor element:

<Button3D href="https://example.com" type="primary">
  Visit Website
</Button3D>

Use the element prop to integrate custom components like Next.js Link:

import Link from 'next/link';
<Button3D element={Link} href="/dashboard" type="primary">
  Go to Dashboard
</Button3D>

API Reference

Button3D Props

CSS Variables

The component exposes CSS variables for theme customization. Override these variables to modify appearance:

Dimensions and Layout

• –button-default-height: Base button height (40px for md)
• –button-default-font-size: Text size (14px)
• –button-default-border-radius: Corner radius (6px)
• –button-horizontal-padding: Left and right padding (18px)

3D Effect and Animation

• –button-raise-level: Height of 3D effect (5px)
• –button-pressed-level: Depth when pressed (0px)
• –button-hover-pressure: Hover tilt intensity (2)
• –transform-speed: Animation duration (0.185s)

Typography

• –button-font-family: Font family (inherit)
• –button-font-weight: Font weight (600)
• –button-letter-spacing: Character spacing (0px)

Colors Per Button Type

Replace {type} with primary, secondary, tertiary, success, error, warning, info, anchor, or danger:

• –button-{type}-color: Background color
• –button-{type}-color-dark: Shadow and pressed state color
• –button-{type}-color-light: Text and icon color
• –button-{type}-color-hover: Hover state background
• –button-{type}-border: Border style

FAQs

Q: Does React 3D Button work with Next.js App Router?
A: React 3D Button functions with Next.js 13+ and the App Router. Add the ‘use client’ directive at the top of your component file to enable client-side interactivity.

Q: How do I customize button colors?
A: Override CSS variables in your stylesheet. Target the .aws-btn class and define variables like –button-primary-color and –button-primary-color-dark. You can also import one of six pre-built themes through the themes directory.

Q: Why are my button styles not loading?
A: Import the base stylesheet with import 'react-3d-button/styles'. Verify import order if using themes. Base styles must load before theme files to prevent cascade issues.

Q: How do I create icon-only buttons?
A: Set the iconOnly prop to true. This removes horizontal padding and creates a square button. Combine with rounded=”full” to create circular icon buttons.