React 3D Icons

A premium, interactive React component library for high-fidelity 3D and 2D vector icons, designed for modern web applications. Powered by React Three Fiber and Three.js, it offers responsive controls, custom styling presets, dynamic angles, lighting adjustments, and a seamless 2D SVG fallback system.

Key Features

• Procedural 3D Canvas: Renders real-time 3D geometries with interactive OrbitControls (pan/rotate/zoom on hover/drag).
• 8 Curated Material Presets:
  • glass: Sleek semitransparent glossy finish.
  • metal: Highly reflective silver/metallic finish.
  • clay: Matte soft rose clay texture.
  • hologram: Vibrant glowing violet futuristic material.
  • gold: Premium beveled reflective gold plating.
  • glassmorphism: Elegant frosted glass overlays with high transmission.
  • carbon: Detailed dark carbon fiber look.
  • wood: Diffuse warm organic timber texture.
• Sizing Flexibility: Directly set size using the size prop as a number (resolves to pixels, e.g., 120 -> 120px) or any valid CSS string (e.g. 8rem, 10vw, etc.).
• Camera Angle Controls: View icons from front, perspective, or tilted orientations out-of-the-box.
• WebGL Check & 2D Vector Fallback: Automatically falls back to handcrafted, lightweight, premium 2D SVGs if WebGL is unavailable on the client browser. Can also be explicitly triggered via variant="2d".
• Contrast Adaptation: Dynamically adjusts glassmorphic highlights and 2D vector outline strokes to contrast perfectly against light or dark canvas backgrounds.

Installation

Install the package and its peer dependencies:

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

Quick Start

import React from "react";
import { ShieldIcon, CrownIcon } from "r3d-icons";

function App() {
  return (
    <div style={{ display: "flex", gap: "20px" }}>
      {/* 3D Glass Shield Icon */}
      <ShieldIcon size={120} preset="glass" angle="perspective" color="#0d9488" />

      {/* 3D Gold Royal Crown */}
      <CrownIcon size={120} preset="gold" angle="front" interactive={true} />

      {/* 2D Fallback Vector Emoji */}
      <ShieldIcon size={120} variant="2d" color="#ef4444" />
    </div>
  );
}

export default App;

TypeScript Support & Type-only Imports

The library provides strict TypeScript definitions for all component parameters. You can import type interfaces directly, including type-only imports to preserve a minimal runtime bundle footprint:

import { ShieldIcon } from "r3d-icons";
import type { ShieldIconProps, IconPreset } from "r3d-icons";

const config: ShieldIconProps = {
  preset: "glassmorphism", // strictly validated literal presets
  color: "#4f46e5"
};

export default function Card() {
  return <ShieldIcon {...config} />;
}

WebGL Memory & Context Management

To prevent browser crashes and screen flickering caused by WebGL context limits (usually a maximum of 8–16 active contexts per page), the library automatically handles cleanup:

• Instant Garbage Collection: On component unmount, r3d-icons instantly forces the browser to discard the WebGL context using the native WEBGL_lose_context extension.
• Resource Disposal: All materials, geometries, and renderer structures are automatically disposed of during unmounting.
• Responsive 2D Fallbacks: For layouts displaying grids of many icons simultaneously, use the variant="2d" prop to run lightweight vector graphics without creating WebGL contexts.

API Properties Reference

Every icon component accepts the following customizable props:

| Prop | Type | Default | Description | | ------------- | ----------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------- | | size | number \| string | 100% (fill container) | Scale of the icon viewport (e.g. 120 or "6rem"). | | preset | "glass" \| "metal" \| "clay" \| "hologram" \| "gold" \| "glassmorphism" \| "carbon" \| "wood" | "glass" | Material skin preset. | | angle | "front" \| "perspective" \| "tilted" | "perspective" | Camera preset viewing angle. | | variant | "3d" \| "2d" | "3d" | Switch between WebGL 3D Canvas and 2D SVG fallback. | | color | string | Icon brand default | Main hexadecimal primary mesh/stroke color. | | accentColor | string | Icon default accent | Glow/emissive or detail styling color. | | spinSpeed | number | 1.0 | Coefficient multiplier for rotation and float cycles. | | floatHeight | number | 1.0 | Amplitude height for the hover floating animation. | | theme | "light" \| "dark" | "dark" | Active ambient lighting contrast scheme. | | interactive | boolean | true | Enables click-and-drag rotation and zoom. |

Icon Catalog (Over 230+ Premium Icons)

Features a massive library of stylized icons across diverse categories including:

• Brands: YouTube, Github, Facebook, Figma, Google, Twitter, etc.
• Hardware: Cpu, Monitor, Keyboard, Mouse, HardDrive, Gamepad, Webcam, RamStick, Motherboard, Gpu.
• Storage & Systems: Database, Cloud, Network, Server, Router, Folder.
• Mechanics: Gear, Wrench, Bolt, Nut, Hammer, Screwdriver, Sprocket, Bearing, Piston, Spring, Turbine, etc.
• Nature (Animals & Flowers): Dog, Cat, Bird, Elephant, Owl, Turtle, Dolphin, Rose, Sunflower, Tulip, Lotus, Daisy, Hibiscus, Orchid, Lily, Cactus, Lavender.
• Utility: Shield, Bell, Alarm, Lock, MapPin, CreditCard, Search, Trash, Cart, Music, Trophy, Star, Heart, Chat, Key, etc.
• Alphabet (A-Z) & Digits (0-9): Bold, beveled beveled text characters.