react-scrolling-background

GPU-based subtle scrolling background, support Content Security Policy, reduced motion, sub-pixel movement, and auto stop.

Background

Check out the live demo.

This component is a fancy scrolling background to enhance simple projects.

Note: despite the scrolling effect is purely based on CSS with GPU support, a large portion of the website will need to be updated frequently. Inevitably, this is putting a huge toll on CPU. Please use this component with care.

How to use

The background component is a standalone component. It can be configured using React props and CSS custom properties.

Configuring using React props

import { ScrollingBackground } from 'react-scrolling-background';

render(
  <ScrollingBackground
    backgroundColor="red"
    backgroundImage={`url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'...`}
  />
);

Configuring using CSS custom properties

import { ScrollingBackground } from 'react-scrolling-background';

render(
  <ScrollingBackground
    style={{
      '--react-scrolling-background__background-color': 'red',
      '--react-scrolling-background__background-image': `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'...`
    }}
  />
);

API

React component

const ScrollingBackground = ({
  backgroundColor?: string;
  backgroundImage?: string;
  className?: string;
  duration?: number;
  nonce?: string;
  speed?: number;
  style?: CSSProperties;
}) => ReactElement;

CSS custom properties

When setting custom properties via CSS stylesheet, sets the CSS custom properties under the react-scrolling-background__vars element.

.react-scrolling-background__vars {
  --react-scrolling-background__background-color: <color>;
  --react-scrolling-background__background-image: <image>;
  --react-scrolling-background__duration: <time>;
  --react-scrolling-background__speed: <number>;
}

Options

Props name	Type	Description
backgroundColor	string/<color>	Background color CSS property. Can also specify via CSS custom property --react-scrolling-background__background-color.
backgroundImage	string/<image>	Background image CSS property. Can also specify via CSS custom property --react-scrolling-background__background-image.
className	string	CSS class to apply to the background container element.
duration	number/<time>	Durations (in milliseconds) to scroll the background. Defaults to 10 minutes. Can also specify via CSS custom property --react-scrolling-background__duration.
nonce	string	Nonce for allowlisting specific elements under content security policy. This package requires script-src and style-src.
speed	string/<number>	Speed of the scrolling defined by number of full rotations done within the duration. Defaults to 3, meaning 3 full rotations in 10 minutes. Note: Speed will change depends on the container width. Narrower container will have its background scroll slower than wider container. Can also specify via CSS custom property --react-scrolling-background__speed.
style	CSS.Properties	CSS properties to apply to the main element.

CSS selectors

Selector	Description
.react-scrolling-background__image	Background image element.
.react-scrolling-background__vars	Content element for storing all CSS custom properties.

Behaviors

Setting CSS custom property to initial is not working in Firefox

As of this writing, Firefox 120 does not support CSS.registerProperty and @property rule yet. Setting a custom property to initial will not reset it back to the default value.

Should I use React props or CSS custom properties?

react-scrolling-background supports 2 ways to configure: React props and CSS custom properties.

Unless certain effect is required, we recommend using React props. Compare to CSS custom properties, props provides best type-safety features.

How can I modify background-size and other CSS properties of the background image?

You can use the CSS selector .react-scrolling-background__image to select the image element and set background-size and various CSS properties. Additional CSS selectors can be found in this section.

Credits

"Hero Patterns" by Steve Schoger is licensed under CC BY 4.0.

Contributions

Like us? Star us.

Want to make it better? File us an issue.

Don't like something you see? Submit a pull request.