Join our Discord community
Dock

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.

Loading component...

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

PropTypeDefaultDescription
appsDockApp[]-Array of app objects to display in the dock
onAppClick(appId: string) => void-Callback function when an app is clicked
openAppsstring[][]Array of app IDs that are currently open (shows indicator dot)
classNamestring''Additional CSS classes to apply to the dock

DockApp Interface

PropertyTypeDescription
idstringUnique identifier for the app
namestringDisplay name of the app (used for tooltips)
iconstringURL 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:

  1. Cosine-based scaling: Uses original macOS cosine algorithm for authentic icon magnification behavior
  2. Dynamic positioning: Real-time calculation of icon positions based on scale transformations
  3. Smooth interpolation: Linear interpolation with optimized frame rates for natural motion
  4. 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