Package Exports

@sreedev/my3dui
@sreedev/my3dui/package.json

Readme

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 my3dui react react-dom
# or
yarn add my3dui react react-dom
# or
pnpm add my3dui react react-dom

Optional Dependencies

For 3D component support, install the following packages:

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

Quick Start

Basic Button3D Component

import React from 'react';
import { Button3D } from 'my3dui';

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

Card3D Component

import { Card3D } from '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 { 
  Button, 
  Input, 
  Select, 
  Badge,
  Card 
} from '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>
        <Button>Submit</Button>
      </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 '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 '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 '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 '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 '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 '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/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 '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

Code Splitting: Import components individually

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

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

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

Memoization: Wrap expensive components

const MemoizedGallery = React.memo(Gallery3D);

SSR Compatibility: Only render 3D on client

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

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Write tests
Submit a pull request

License

MIT License - see LICENSE file for details

Support

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

@sreedev/my3dui