macOS Dock
Pixel-perfect macOS dock replica with authentic magnification physics and responsive design. A free open source React component for Next.js featuring TypeScript integration and Tailwind CSS compatibility.
Installation
npx shadcn@latest add https://www.shadcn.io/registry/mac-os-dock.json
npx shadcn@latest add https://www.shadcn.io/registry/mac-os-dock.json
pnpm dlx shadcn@latest add https://www.shadcn.io/registry/mac-os-dock.json
bunx shadcn@latest add https://www.shadcn.io/registry/mac-os-dock.json
Features
- Free open source React component built for Next.js applications with authentic macOS dock experience
- Pixel-perfect cosine algorithm replicating Apple's original magnification physics using advanced JavaScript mathematics
- TypeScript-first development with comprehensive type definitions and IntelliSense support for reliable development
- Responsive adaptive design that automatically scales icons and effects based on screen dimensions
- Tailwind CSS integration for seamless styling, backdrop blur effects, and responsive design patterns
- shadcn/ui compatibility following modern component architecture and design system conventions
- 60fps smooth animations with requestAnimationFrame optimization and performance monitoring
- Interactive bounce effects with optional GSAP integration for enhanced click animations
- App state management with visual indicators for running applications and proper state tracking
- Performance optimized with throttled mouse tracking, efficient calculations, and memory management
- Mobile-friendly touch support with appropriate scaling and responsive behavior across all devices
- Professional styling with authentic backdrop blur, shadows, and glassmorphism effects
Usage
The MacOSDock component requires an array of apps and a callback function for handling app clicks:
import { MacOSDock } from '@/components/ui/mac-os-dock';
const apps = [
{
id: 'finder',
name: 'Finder',
icon: 'https://cdn.jim-nielsen.com/macos/1024/finder-2021-09-10.png'
},
// ... more apps
];
const [openApps, setOpenApps] = useState(['finder']);
<MacOSDock
apps={apps}
onAppClick={(appId) => console.log('Clicked:', appId)}
openApps={openApps}
/>
Props
MacOSDock
Prop | Type | Default | Description |
---|---|---|---|
apps | DockApp[] | - | Array of app objects to display in the dock |
onAppClick | (appId: string) => void | - | Callback function when an app is clicked |
openApps | string[] | [] | Array of app IDs that are currently open (shows indicator dot) |
className | string | '' | Additional CSS classes to apply to the dock |
DockApp Interface
Property | Type | Description |
---|---|---|
id | string | Unique identifier for the app |
name | string | Display name of the app (used for tooltips) |
icon | string | URL or path to the app icon image |
Responsive Behavior
The dock automatically adjusts its appearance based on screen size:
- Mobile (< 480px): Smaller icons with reduced magnification
- Tablet (480-768px): Medium-sized icons with moderate magnification
- Desktop (> 768px): Full-sized icons with maximum magnification effect
Performance Features
- Throttled Mouse Tracking: Limits mouse move events to 60fps for optimal performance
- Animation Optimization: Uses requestAnimationFrame for smooth animations
- Efficient Calculations: Cosine-based algorithm matches macOS behavior exactly
- Memory Management: Proper cleanup of event listeners and animation frames
Advanced Usage
With GSAP Integration
For enhanced bounce animations, include GSAP in your project:
// The component automatically detects and uses GSAP if available
import { gsap } from 'gsap';
// GSAP will be used for more sophisticated bounce animations
<MacOSDock
apps={apps}
onAppClick={handleAppClick}
openApps={openApps}
/>
Custom Styling
The dock uses responsive calculations but can be customized with CSS:
<MacOSDock
apps={apps}
onAppClick={handleAppClick}
className="shadow-2xl border-2 border-white/20"
/>
Use Cases
This free open source React component is perfect for:
- Next.js portfolios - Showcase applications with authentic macOS desktop experience using TypeScript safety
- Creative dashboards - Build sophisticated navigation interfaces with professional Apple-inspired design
- Desktop applications - Create familiar dock navigation using shadcn/ui patterns and responsive scaling
- SaaS platforms - Implement memorable application launchers with smooth animations and JavaScript physics
- Portfolio websites - Display projects with iconic macOS dock aesthetics using Tailwind CSS styling
- Admin interfaces - Design intuitive navigation systems with authentic magnification effects and open source flexibility
- Design systems - Integrate premium dock components into existing component libraries
Technical Details
Authentic macOS Algorithm
The component replicates Apple's exact magnification mathematics:
- Cosine-based scaling: Uses original macOS cosine algorithm for authentic icon magnification behavior
- Dynamic positioning: Real-time calculation of icon positions based on scale transformations
- Smooth interpolation: Linear interpolation with optimized frame rates for natural motion
- Responsive calculations: Adaptive sizing that maintains authenticity across all screen dimensions
Performance Optimizations
- RequestAnimationFrame loops with 60fps targeting and performance monitoring for smooth animations
- Throttled mouse tracking limiting events to optimal frequencies for efficient processing
- TypeScript-optimized component structure with proper memory management and type validation
- Tailwind CSS backdrop effects with hardware-accelerated blur and glassmorphism rendering
- Efficient calculation caching minimizing redundant mathematical operations
Advanced Features
- GSAP integration for enhanced bounce animations with sophisticated easing functions
- Responsive breakpoint system with mobile, tablet, and desktop optimizations
- App state indicators with precise dot positioning and visual feedback
- High-resolution icon support maintaining crispness at all magnification levels
Accessibility
This open source component includes comprehensive accessibility features:
- Semantic navigation structure with proper ARIA labels and tooltip implementation for screen readers
- Keyboard navigation support with focus management and accessible interaction patterns
- React-compatible accessibility when used in interactive Next.js applications
- High contrast support with customizable styling that adapts to different accessibility needs
- Touch-friendly design with appropriate hit targets and responsive scaling across all devices
Implementation Notes
- Icons should be high-resolution (1024px recommended) for crisp display at all scales
- The component maintains aspect ratios automatically
- App state indicators appear as small dots below open applications
- Click handlers receive the app ID for easy state management
LimelightNav
Smart navigation component with dynamic limelight highlighting and adaptive width. A JavaScript-powered React component for Next.js featuring TypeScript integration and shadcn/ui compatibility.
Menu Dock
Versatile dock navigation with responsive variants, dual orientations, and smooth animations. A free open source React component for Next.js with TypeScript support and shadcn/ui design token integration.