Add Film Grain & Noise Textures to Images and Backgrounds with Pixlated Web Components

Preview:

Description:

Pixlated is a lightweight web component library that applies customizable film grain and noise textures to images and backgrounds using the Canvas API.

The library currently comes with 2 custom elements, <pixlated-image> and <pixlated-bg>, to handle images and container backgrounds.

Features:

• Two Specialized Components: <pixlated-image> for image grain effects and <pixlated-bg> for background noise textures.
• Zero Dependencies: Built entirely on native Web Components API and Canvas 2D context.
• High-Performance Rendering: Uses Canvas API with device pixel ratio scaling for crisp output on retina displays.
• Responsive Design: Components automatically adapt to container dimensions and respond to resize events.
• Framework Agnostic: Works in vanilla JavaScript, React, Vue, Angular, or any other framework that supports custom elements.

Use Cases:

• Vintage Photography Portfolios: Add authentic film grain to digital images for photography websites.
• Dark Mode Interfaces: Enhance dark backgrounds with subtle texture to reduce eye strain.
• Art Direction: Create specific moods and aesthetics without editing original image files.

How To Use It:

1. Install & import pixlated with NPM.

# NPM
$ npm install pixlated
import 'pixlated';

2. For static sites or quick demos, use the CDN link. You can load both components or just the one you need.

<script src="https://unpkg.com/pixlated/src/pixlated.js"></script>
<script src="https://unpkg.com/pixlated/src/pixlated-bg.js"></script>

3. Apply a grain effect directly to an image using the <pixlated-image> component. It works just like a standard <img> tag but renders the image on a canvas.

Available Props:

<pixlated-image
  src="path/to/your/photo.jpg"
  intensity="0.2"
  width="600"
  height="400"
  alt="A photo with a subtle grain effect."
>
</pixlated-image>

4. Add a noisy texture to the background of any container element.

Available Props:

<pixlated-bg intensity="0.15" color="#1a1a1a">
  <h1>Your Hero Title</h1>
  <p>This container has a nice, subtle texture.</p>
</pixlated-bg>

5. Style the web components with CSS. They behave like standard block-level or inline-block elements.

pixlated-image {
  border-radius: 12px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  display: block;
  margin: 2rem auto;
}
pixlated-bg {
  padding: 2rem;
  border-radius: 8px;
  min-height: 300px;
}

6. API methods.

// reload()
// Redraws the grain effect with current attributes. 
// Useful when you need to regenerate the random noise pattern.
const image = document.querySelector('pixlated-image');
image.reload();
// getConfig()
// Returns an object with the current configuration values:
const config = image.getConfig();
// Returns: { src, intensity, width, height, alt }

7. Event handlers.

// pixlated:loaded
// Fires when the source image successfully loads. 
// The event detail includes the image source URL and natural dimensions.
image.addEventListener('pixlated:loaded', (e) => {
  console.log('Image loaded:', e.detail);
  // { src: 'photo.jpg', width: 1920, height: 1080 }
});
// pixlated:error
// Fires when the image fails to load. 
// The event detail includes the attempted source URL and error information.
image.addEventListener('pixlated:error', (e) => {
  console.error('Load failed:', e.detail);
  // { src: 'photo.jpg', error: 'error', message: 'Failed to load image' }
});

FAQs

Q: The grain effect looks different on retina displays compared to standard screens. How do I ensure consistency?
A: Pixlated automatically handles device pixel ratio scaling by multiplying the canvas dimensions by window.devicePixelRatio.If you’re seeing differences, check that you haven’t overridden the canvas styles or scaled the element with CSS transforms.

Q: My images are on a different domain and not rendering. What’s causing this?
A: The component sets crossOrigin="anonymous" on the image element to allow canvas manipulation of cross-origin images. Your image server needs to send the appropriate CORS headers (Access-Control-Allow-Origin) for this to work.

Q: Does changing the intensity attribute dynamically update the effect immediately?
A: Yes, both components observe attribute changes and redraw automatically. You can update intensity, color, dimensions, or any other attribute and see the changes immediately. The component uses attributeChangedCallback to detect changes and triggers a redraw.

Q: How does this perform compared to using CSS filters for a similar effect?
A: Canvas-based grain generally performs better for static effects because the rendering happens once rather than continuously. CSS filters run on every frame and can cause repaints during scrolling or animations. The tradeoff is that canvas requires more initial setup and JavaScript execution.