Create a Single Gradient/Image Background across Multiple Elements – ShareShade

ShareShade is a lightweight JavaScript library that creates a single image or gradient background across multiple DOM elements.

It creates the illusion of visual continuity between separate HTML elements by calculating their positions and applying a custom CSS background that spans them all.

Features:

• No manual CSS imports: Automatically injects necessary styles.
• Framework agnostic: Works with Vanilla JS, React, Vue, Angular, and Next.js.
• Simple API with update and destroy methods for lifecycle management.
• Automatic resize handling: Recalculates on window resize events.
• Customizable opacity for the overlay effect.

How to use it:

1. Install and import ShareShade with NPM.

# NPM
$ npm install shareshade

// Vanilla JS
<script type="module">
import ShareShade from 'https://cdn.jsdelivr.net/npm/[email protected]/+esm';
</script>
// React/Next.js/Vue.js/Angular
import ShareShade from 'shareshade';
import 'shareshade/shareshade.css';

2. Initialize it with your target elements and configure the background shared in the ‘background’:

new ShareShade({
  selector: '.element',
  background: 'background or gradient here'
});

3. Customize the opacity of the overlay (default: 1).

new ShareShade({
  selector: '.element',
  background: 'background or gradient here',
  opacity: .8,
});

4. Manually forces a recalculation of the overlay. It’s called automatically on window resize.

instance.update()

5. Destroy the instance and remove the overlay & all event listeners. This is useful for cleanup in single-page applications.

instance.destroy()

How It Works

When you initialize ShareShade, it first finds all DOM elements matching your selector. It then iterates through them to calculate a single, large bounding box that encompasses all of them combined. It finds the minimum top/left coordinates and the maximum bottom/right coordinates across the entire set of elements.

Next, it loops through each target element again. For each one, it creates a <div> that acts as the overlay. This overlay is positioned absolutely within the target element, covering it completely. The magic is in how the background is set. The background-image is set to your specified gradient or image. The background-size is set to the width and height of the total bounding box calculated earlier. Finally, background-position is adjusted with a negative offset. This offset effectively “moves” the large background so that only the correct portion is visible within that specific element’s overlay.

The result is a collection of separate overlays, each showing a different “slice” of the same large background, creating the illusion of a single, continuous surface.

FAQS

Q: Why do my elements shift position after initialization?
A: This happens if your elements don’t have position: relative set. ShareShade sets position: relative on target elements to properly position the overlay. If you’re seeing layout shifts, explicitly set position: relative in your CSS for those elements before ShareShade initializes.

Q: Can I update the gradient after initialization?
A: Absolutely. Call the update method with new styles: shade.update({ background: 'new-gradient-here' }). This recalculates everything with your new background value.

Q: Does this work with CSS transforms or scaled elements?
A: Not perfectly. The library uses getBoundingClientRect() which accounts for transforms, but the overlay positioning can get tricky with non-identity transforms