react-ambient-light

A React component that creates beautiful ambient light effects for images and videos with customizable glow, blur, and scale options.

Installation

npm install react-ambient-light

pnpm add react-ambient-light

yarn add react-ambient-light

Features

• Ambient light effect for images and videos
• Customizable blur, scale, and opacity
• Video synchronization support
• TypeScript support with full type definitions
• Lightweight and performant
• SSR compatible
• Accessibility features built-in

Usage

Basic Image Example

import { AmbientLight } from 'react-ambient-light';

function App() {
  return (
    <AmbientLight
      src="https://example.com/image.jpg"
      type="image"
      blur={40}
      scale={1.1}
      opacity={0.6}
    />
  );
}

Basic Video Example

import { AmbientLight } from 'react-ambient-light';

function App() {
  return (
    <AmbientLight
      src="https://example.com/video.mp4"
      type="video"
      videoAutoPlay={true}
      videoLoop={true}
      videoMuted={true}
    />
  );
}

Advanced Example with Children

import { AmbientLight } from 'react-ambient-light';

function App() {
  return (
    <AmbientLight
      src="https://example.com/video.mp4"
      type="video"
      blur={50}
      scale={1.2}
      opacity={0.7}
      className="my-ambient-light"
      style={{ borderRadius: '16px' }}
    >
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          color: 'white',
          fontSize: '2rem',
        }}
      >
        <h1>Overlay Content</h1>
      </div>
    </AmbientLight>
  );
}

Using the useDominantColor Hook

Extract the dominant color from an image:

import { useDominantColor } from 'react-ambient-light';

function ColorDisplay() {
  const color = useDominantColor('https://example.com/image.jpg');

  return <div style={{ backgroundColor: color, padding: '20px' }}>Dominant color: {color}</div>;
}

API Reference

AmbientLight Component

Props

Prop	Type	Default	Description
src	string	required	URL of the image or video
type	'image' | 'video'	'image'	Type of content
blur	number	40	Blur intensity of the glow (in pixels)
scale	number	1.1	Scale factor for the glow expansion
opacity	number	0.6	Opacity of the glow (0 to 1)
className	string	''	Custom CSS class for the container
style	CSSProperties	{}	Custom inline styles for the container
children	ReactNode	undefined	Optional content to overlay on top
alt	string	'Content'	Alternative text for the image
onLoad	() => void	undefined	Callback when the image/video loads
onError	() => void	undefined	Callback when there's an error loading

Video-specific Props

Prop	Type	Default	Description
videoAutoPlay	boolean	true	Enable autoplay for videos
videoControls	boolean	false	Show video controls
videoLoop	boolean	true	Loop the video
videoMuted	boolean	true (when autoPlay is true)	Mute the video

useDominantColor Hook

Extract the dominant color from an image.

const color = useDominantColor(imageSrc: string): string

Parameters:

• imageSrc (string): URL of the image

Returns:

• string: RGB color value (e.g., 'rgb(255, 128, 64)')

Examples

Responsive Image with Custom Styling

<AmbientLight
  src="image.jpg"
  blur={60}
  opacity={0.8}
  style={{
    maxWidth: '600px',
    margin: '0 auto',
    borderRadius: '20px',
  }}
  alt="Beautiful landscape"
/>

Video Player with Controls

<AmbientLight
  src="video.mp4"
  type="video"
  videoControls={true}
  videoAutoPlay={false}
  videoMuted={false}
  blur={30}
  scale={1.15}
/>

Image Gallery Card

<AmbientLight src="artwork.jpg" blur={45} scale={1.2} opacity={0.5} className="gallery-card">
  <div className="card-overlay">
    <h3>Artwork Title</h3>
    <p>Artist Name</p>
  </div>
</AmbientLight>

Error Handling

<AmbientLight
  src="image.jpg"
  onLoad={() => console.log('Image loaded successfully')}
  onError={() => console.error('Failed to load image')}
/>

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

TypeScript

This package is written in TypeScript and includes type definitions out of the box.

import type { AmbientLightProps } from 'react-ambient-light';

const props: AmbientLightProps = {
  src: 'image.jpg',
  type: 'image',
  blur: 40,
};

Performance Considerations

• The component uses React.memo to prevent unnecessary re-renders
• Images use lazy loading by default
• Videos are synchronized efficiently using refs
• The glow layer has pointer-events: none to avoid interfering with interactions

Accessibility

• Images include proper alt attributes
• Glow layers are hidden from screen readers with aria-hidden="true"
• Videos include playsInline for mobile compatibility
• Decorative glow videos have tabIndex={-1} to prevent focus

Contributing

Contributions are always welcome!

Please follow our contributing guidelines.

Please adhere to this project's CODE_OF_CONDUCT.

Issues

Report issues at Issues.

License

Licensed under the MIT License.

See LICENSE for more information.