circle-photo-viewer

A lightweight, high-performance React component for displaying circular profile pictures with a built-in, elegant, and responsive full-screen image viewer.

Features

• 🌕 Perfect Circular Design: Automatic centering and cropping.
• 🖼️ Elegant Viewer: One-click to view the full image in a professional modal.
• 💨 Lightweight & Fast: Built with React and TypeScript, optimized for bundle size.
• 🎨 Fully Customizable: Control size, colors, animations, and more.
• ⌨️ Accessibility First: ARIA support and keyboard interaction (ESC to close).
• 📱 Mobile Ready: Fully responsive transitions and touch-friendly controls.

Installation

npm install circle-photo-viewer lucide-react clsx
# or
yarn add circle-photo-viewer lucide-react clsx

Basic Usage

import { CircleViewer } from 'circle-photo-viewer';
import 'circle-photo-viewer/styles.css'; // Just import it once!

function ProfileInfo() {
  return (
    <div className="flex flex-col items-center gap-4">
      <CircleViewer 
        src="https://images.unsplash.com/photo-1535713875002-d1d0cf377fde" 
        size={150} 
        alt="John Doe" 
      />
      <h2>John Doe</h2>
    </div>
  );
}

Props

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | src | string | Required | The source URL of the image. | | size | number \| string | 150 | Diameter of the circle. | | alt | string | 'Profile Picture' | Alt text for the image. | | overlayColor | string | rgba(0,0,0,0.85) | Backdrop color of the fullscreen viewer. | | closeIconColor| string | white | Color of the X icon in the viewer. | | animationDuration | number | 300 | Duration of the opening animation in ms. | | className | string | - | Custom class for the circular container. | | onOpen | () => void | - | Callback triggered when the viewer opens. | | onClose | () => void | - | Callback triggered when the viewer closes. |

License

MIT © Antigravity