My3DUI - Modern 3D-Inspired UI Component Library

A TypeScript React component library combining beautiful 2D UI components with cutting-edge 3D visual effects using Three.js. Built on top of shadcn/ui, Radix UI, Framer Motion, and @react-three/fiber for maximum flexibility and extensibility.

Features

🎨 Rich Component Library

• 50+ pre-built UI components
• 3D-enhanced variants of common components
• Fully TypeScript support
• Dark mode support via next-themes
• Fully customizable with Tailwind CSS

🎬 3D Visual Effects

• Three.js integration via @react-three/fiber
• Bloom effects and post-processing
• Particle systems and animations
• 3D model viewers and galleries
• Custom WebGL effects

🎭 Animation & Motion

• Framer Motion integration
• Smooth transitions and interactions
• Spring animations
• Gesture controls

📦 Developer Experience

• ESM, CJS, and type declarations included
• Tree-shakeable exports
• Full TypeScript support
• No peer dependency conflicts
• Modular imports for code-splitting

Installation

npm install @sreedev/my3dui react react-dom
# or
yarn add @sreedev/my3dui react react-dom
# or
pnpm add @sreedev/my3dui react react-dom

Styles (zero-config)

Styles load automatically when you import any component from @sreedev/my3dui. You do not need to import CSS manually.

import { Button3D, ThemeProvider } from "@sreedev/my3dui";
// That's it — design tokens and Tailwind utilities are already loaded

The built CSS (Tailwind base/components/utilities and theme tokens for :root, .dark, .neon, .glass, .corporate, .vibrant) is bundled with the library and injected when your bundler resolves the package. You do not need to install Tailwind in your app. Optional: if you need to load styles without importing a component (e.g. for SSR or a custom entry), you can still do import "@sreedev/my3dui/styles.css".

Optional Dependencies

For 3D component support, install the following packages:

npm install three @react-three/fiber @react-three/drei

Exported Components

All components are exported from the main entry. Use tree-shaking for optimal bundle size.

Layout: Container, Grid, Stack, Section, PageLayout, Stage, Viewport, Container3D, Grid3D, CameraController, Scene3D

3D UI: Button3D, Card3D, Accordion3D, Badge3D, Input3D, Slider3D, Tabs3D, Toggle3D, Modal3D, Menu3D, Menu3DItem, Menu3DLabel, Menu3DSeparator, Tooltip3D, Progress3D, ResizablePanelGroup, ResizablePanel, ResizableHandle, Select3D, Spinner3D, Stepper3D, NavBar3D, Timeline3D

Standard UI: Tooltip, TooltipProvider, Slider, Toggle, Badge, Input, Select, Table, Pagination, Progress, Skeleton, Toast, Toaster, SonnerToaster, sonnerToast, Popover, Sheet, Dialog, Breadcrumb, Label, Checkbox, Switch, Textarea, Separator, ScrollArea, ScrollBar, RadioGroup, ToggleGroup, Alert, Avatar, Card, Collapsible, AspectRatio, HoverCard, AlertDialog, Command, Form, DropdownMenu, ContextMenu, Drawer, Menubar, NavigationMenu, Calendar, Sidebar, Carousel, InputOTP, and subcomponents.

Data viz: BarChart3D, LineChart3D, PieChart3D, ScatterPlot3D, Graph3D, Map3D

Media: Gallery3D, ModelViewer, VideoPlane, ImagePlane, AudioVisualizer

Effects: Particles, Bloom, Reflection, Fog, ShadowSystem, GlowEffect, WaveEffect, NoiseField

Theme: ThemeProvider, useTheme, useThemeOptional, ThemeName

Multi-theme system

My3DUI ships with six themes controlled by a class on document.documentElement. Use ThemeProvider to switch themes and persist the choice.

Themes: light (default), dark, neon, glass, corporate, vibrant

import { ThemeProvider, useTheme } from "@sreedev/my3dui";
import "@sreedev/my3dui/styles.css";

function App() {
  return (
    <ThemeProvider defaultTheme="light" storageKey="my3dui-theme">
      <Demo />
    </ThemeProvider>
  );
}

function Demo() {
  const { theme, setTheme } = useTheme();
  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
      <option value="neon">Neon</option>
      <option value="glass">Glass</option>
      <option value="corporate">Corporate</option>
      <option value="vibrant">Vibrant</option>
    </select>
  );
}

All components use CSS variables for colors, so they automatically adapt to the active theme. No extra Tailwind setup is required in the consumer app when using the built CSS.

Design system

Design tokens

The library uses two layers of tokens:

1. CSS variables (in styles.css) — Drive theming; values are RGB triplets so Tailwind can apply opacity:

• Colors: --color-primary, --color-primary-foreground, --color-secondary, --color-accent, --color-danger, --color-success, --color-warning, --color-background, --color-foreground, --color-surface, --color-border, --color-text-primary, --color-text-secondary, --color-ring, --color-muted, --color-muted-foreground
• Shadows: --shadow-soft, --shadow-glow
• Radius: --radius-sm, --radius-md, --radius-lg, --radius-xl, --radius-2xl, --radius-full

Each theme (:root, .dark, .neon, .glass, .corporate, .vibrant) sets these variables.

2. JS tokens (in lib/tokens.ts) — Spacing scale, z-index scale, duration, breakpoints for layout and animation. Used by layout components and shared utilities.

Variants (CVA)

Components use class-variance-authority for consistent variant APIs:

• Size: xs, sm, md, lg, xl, icon (and icon-sm, icon-lg where applicable).
• Color: primary, secondary, accent, danger, success, warning, info, muted.
• Style: solid, outline, ghost, soft, glass.
• State: loading, disabled, error (where applicable).
• Shape: rounded-sm through rounded-full.
• Elevation: flat, low, medium, high, glow (Card, surfaces).

Shared variant helpers live in lib/variants.ts for internal use; component APIs expose the props that make sense (e.g. Button3D: variant, size, rounded; Badge: variant, size, shape; Input: size, error; Card: elevation).

Layout components

• Container: size, padding, fluid; responsive horizontal padding by default.
• Stack: direction, gap, align, justify, wrap, inline; gap uses spacing scale.
• Grid: cols (number or responsive { sm, md, lg, xl, 2xl }), gap, minColWidth; Tailwind-safe responsive classes.
• Section: fullWidth, background, containerSize, noPadding, paddingY, as (section | div | article).
• PageLayout: header, footer, sidebar, sidebarPosition, sidebarWidth, minHeight.

Accessibility

Components follow common a11y patterns: focus rings (focus-visible:ring-2), aria-invalid on inputs when error, disabled/loading with reduced opacity and pointer-events, and semantic HTML. Radix-based components inherit Radix’s keyboard and screen reader behavior.

Quick Start

Basic Button3D Component

import React from 'react';
import { Button3D } from '@sreedev/my3dui';

export function MyComponent() {
  return (
    <Button3D 
      variant="primary" 
      size="lg"
      onClick={() => console.log('Clicked!')}
    >
      Click Me
    </Button3D>
  );
}

Card3D Component

import { Card3D } from '@sreedev/my3dui';

export function MyCard() {
  return (
    <Card3D className="w-96">
      <div className="p-6">
        <h2 className="text-2xl font-bold">Card Title</h2>
        <p className="text-gray-600">Card content goes here</p>
      </div>
    </Card3D>
  );
}

Using Standard Components

import { 
  Button3D, 
  Input, 
  Select, 
  Badge,
  Card 
} from '@sreedev/my3dui';

export function StandardUI() {
  return (
    <Card>
      <div className="space-y-4">
        <Input placeholder="Enter text..." />
        <Select>
          <option>Option 1</option>
          <option>Option 2</option>
        </Select>
        <Button3D>Submit</Button3D>
      </div>
    </Card>
  );
}

3D Components Guide

Using 3D Effects with Canvas

My3DUI 3D components require a <Canvas> from @react-three/fiber:

import { Canvas } from '@react-three/fiber';
import { Bloom } from '@sreedev/my3dui';

export function MyScene() {
  return (
    <Canvas>
      <Bloom intensity={1.5} radius={0.8} threshold={0.5} />
      {/* Your 3D content */}
    </Canvas>
  );
}

Bloom Effect

import { Canvas } from '@react-three/fiber';
import { Bloom } from '@sreedev/my3dui';

export function BloomExample() {
  return (
    <Canvas>
      <Bloom 
        intensity={1.2}    // Effect intensity
        radius={0.5}       // Blur radius
        threshold={0.2}    // Light threshold
      />
      <mesh>
        <boxGeometry args={[1, 1, 1]} />
        <meshBasicMaterial color="white" emissive="#00ff00" />
      </mesh>
    </Canvas>
  );
}

3D Image/Video Planes

import { Canvas } from '@react-three/fiber';
import { ImagePlane, VideoPlane } from '@sreedev/my3dui';

export function MediaPlanes() {
  return (
    <Canvas>
      <ImagePlane 
        src="/path/to/image.jpg" 
        width={4}
        height={3}
      />
    </Canvas>
  );
}

Gallery3D Component

import { Canvas } from '@react-three/fiber';
import { Gallery3D } from '@sreedev/my3dui';

export function MyGallery() {
  const images = [
    '/image1.jpg',
    '/image2.jpg',
    '/image3.jpg',
  ];

  return (
    <Canvas>
      <Gallery3D images={images} />
    </Canvas>
  );
}

Map3D Component

import { Canvas } from '@react-three/fiber';
import { Map3D } from '@sreedev/my3dui';

export function InteractiveMap() {
  return (
    <Canvas>
      <Map3D 
        latitude={40.7128}
        longitude={-74.0060}
        zoom={12}
      />
    </Canvas>
  );
}

Particle System

import { Canvas } from '@react-three/fiber';
import { Particles } from '@sreedev/my3dui';

export function ParticleEffect() {
  return (
    <Canvas>
      <Particles 
        count={1000}
        color="0x00ff00"
        speed={0.5}
      />
    </Canvas>
  );
}

Component API Reference

Button3D

interface Button3DProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'accent' | 'destructive' | 'outline' | 'ghost' | 'glass';
  size?: 'sm' | 'md' | 'lg' | 'icon' | 'default';
  loading?: boolean;
  asChild?: boolean;
  shadowColor?: string;
}

Card3D

interface Card3DProps extends React.HTMLAttributes<HTMLDivElement> {
  elevation?: number;
  glow?: boolean;
  glowColor?: string;
}

Input3D

interface Input3DProps extends React.InputHTMLAttributes<HTMLInputElement> {
  variant?: 'default' | 'gradient' | 'glass';
  icon?: React.ReactNode;
}

Bloom

interface BloomProps {
  intensity?: number;    // Default: 1.0
  radius?: number;       // Default: 0.4
  threshold?: number;    // Default: 0
}

Particles

interface ParticlesProps {
  count?: number;        // Default: 100
  color?: string;        // Hex color
  speed?: number;        // Default: 1
  size?: number;         // Default: 1
}

Theming

Using next-themes

My3DUI supports dark mode seamlessly via next-themes:

import { ThemeProvider } from 'next-themes';
import MyApp from './App';

export function App() {
  return (
    <ThemeProvider attribute="class">
      <MyApp />
    </ThemeProvider>
  );
}

Custom Tailwind Config

// tailwind.config.js
module.exports = {
  content: [
    './node_modules/@sreedev/my3dui/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      colors: {
        'primary': '#your-color',
      }
    }
  }
}

Peer Dependencies

The following peer dependencies are required:

{
  "react": ">=18.0.0",
  "react-dom": ">=18.0.0",
  "three": ">=0.150.0"
}

Optional peer dependencies for 3D features:

• @react-three/fiber (^8.0.0)
• @react-three/drei (^9.0.0)

Building from Source

# Install dependencies
npm install

# Type checking
npm run lint

# Build library
npm run build

# Watch mode (development)
npm run dev

Project Structure

src/
├── components/
│   ├── layouts/          # Layout components (Container, Stack, Grid, etc.)
│   └── ui/               # UI components (Button3D, Card3D, etc.)
├── hooks/                # Custom React hooks
├── lib/                  # Utility functions
├── index.ts              # Main entry point
└── three-elements.d.ts   # Three.js type declarations

Supported Components

Layouts

• Container - Responsive container wrapper
• Grid - CSS Grid layout component
• Stack - Flexbox stack layout
• Section - Semantic section component
• PageLayout - Full-page layout template
• Stage - 3D stage container
• Scene3D - 3D scene wrapper
• ViewPort - Custom viewport handler

3D Components

• Button3D - 3D-styled button
• Card3D - 3D-enhanced card
• Accordion3D - 3D accordion menu
• Badge3D - 3D badge component
• Input3D - 3D input field
• Slider3D - 3D slider control
• Tabs3D - 3D tab navigation
• Toggle3D - 3D toggle switch
• Modal3D - 3D modal dialog
• Menu3D - 3D context menu
• Tooltip3D - 3D tooltip
• Progress3D - 3D progress bar
• Select3D - 3D select dropdown
• Spinner3D - 3D loading spinner
• Stepper3D - 3D step navigator
• NavBar3D - 3D navigation bar
• Timeline3D - 3D timeline
• Bloom - Bloom post-processing effect
• Particles - Particle system
• ImagePlane - 3D image plane
• VideoPlane - 3D video plane
• Gallery3D - 3D image gallery
• Map3D - 3D interactive map
• ModelViewer - 3D model viewer
• Reflection - Reflection effect
• WaveEffect - Wave animation
• GlowEffect - Glow animation
• AudioVisualizer - Audio-reactive visualizer

Standard UI Components (from shadcn/ui)

• Button - Standard button
• Input - Text input field
• Select - Dropdown select
• Badge - Badge label
• Card - Card container
• Dialog - Modal dialog
• Drawer - Sliding drawer
• Dropdown - Dropdown menu
• Form - Form wrapper
• Tabs - Tab navigation
• Tooltip - Tooltip overlay
• Slider - Slider control
• Toggle - Toggle switch
• Popover - Popover component
• Table - Data table
• Checkbox - Checkbox input
• RadioGroup - Radio button group
• Switch - Toggle switch
• Separator - Visual divider
• Skeleton - Loading skeleton
• Pagination - Page selector
• Calendar - Date picker
• Carousel - Image carousel
• Breadcrumb - Breadcrumb navigation
• Sheet - Side sheet
• Sidebar - Sidebar navigation
• Menubar - Menu bar
• Command Palette - Command search
• Context Menu - Right-click menu
• Alert - Alert box
• And more!

Migration Guide

From shadcn/ui

All My3DUI components maintain compatibility with shadcn/ui styling:

// Before
import { Button } from '@/components/ui/button';

// After - with enhanced features
import { Button3D } from '@sreedev/my3dui';

Variant Changes

Button variants are consistent:

// Works the same
<Button3D variant="outline">Click</Button3D>
<Button3D variant="ghost">Click</Button3D>
<Button3D variant="primary">Click</Button3D>

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Opera (latest)

For 3D features, WebGL support is required.

Performance Tips

1. Code Splitting: Import components individually

   import { Button3D } from '@sreedev/my3dui';  // Better
   // vs
   import * as My3DUI from '@sreedev/my3dui';    // Avoids this

2. Lazy Load 3D Components: Use React.lazy for 3D canvas

   const Scene = React.lazy(() => import('./MyScene'));

3. Memoization: Wrap expensive components

   const MemoizedGallery = React.memo(Gallery3D);

4. SSR Compatibility: Only render 3D on client

   if (typeof window === 'undefined') return null;

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write tests
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Changelog

v0.1.0 (Initial Release)

• Initial component library release
• 50+ components included
• Full TypeScript support
• 3D component suite
• Framer Motion integration
• Tailwind CSS styling
• shadcn/ui component compatibility