react-plasma-background
v1.0.1
Published
React component for creating a background with plasma effect
Downloads
7
Maintainers
Readme
react-plasma-background
A small library for React that provides a background component with a simple plasma effect. The effect is generated randomly based on the passed animation configuration and is built using the Web Animations API🔮.
(Quality cropped because of .gif format)
Usage
- Install using any available package manager:
// Yarn
yarn add react-plasma-background
// npm
npm i react-plasma-background
- Import the
PlasmaBackground
component and use it as is. Pass all your content viachildren
.
import { PlasmaBackground } from "react-plasma-background";
function App() {
return (
<PlasmaBackground
initial={{
blocksColors: ["#ff0000", "#00ff00", "#0000ff"],
}}
>
...
</PlasmaBackground>
);
}
- To control the animation at runtime, the library provides a hook that works only within the scope of the
PlasmaBackground
component.
import { usePlasmaContext } from 'react-plasma-background'
function ChildComponent() {
const {
changeColor,
changeSpeed,
changeOpacity,
changeBlur,
updateConfig,
shake,
} = usePlasmaContext();
return ...
}
- If you want to control the animation outside of the
PlasmaBackground
context, you can pass aRef
object as a prop.
import { useRef, useEffect } from "react"
import { PlasmaBackground, UsePlasmaReturn } from 'react-plasma-background'
function App() {
const plasmaBackgroundRef = useRef<UsePlasmaReturn>(null);
useEffect(() => {
const [config, controls] = plasmaBackgroundRef.current;
}, [])
return (
<PlasmaBackground
ref={plasmaBackgroundRef}
initial={{
blocksColors: ["#ff0000", "#00ff00", "#0000ff"]
}}
>
...
</PlasmaBackground>
)
}
- The library also exposes default configurations, so feel free to use them and override as needed.
import { defaultPlasmaConfig, defaultAnimationConfig } from 'react-plasma-background'
function App() {
return (
<PlasmaBackground
initial={{
...defaultPlasmaConfig,
blocksColors: ["#ff0000", "#00ff00", "#0000ff"],
speed: 20
}}
animationConfiguration={{
...defaultAnimationConfig,
block: {
...defaultAnimationConfig.block,
widthRange: [10, 20],
}
}}
>
...
</PlasmaBackground>
)
}
API Reference
Types
PlasmaConfig
type PlasmaConfig = {
blocksColors: PlasmaColorTuple;
speed: number;
opacity: number;
blur: number;
};
- blocksColors:
PlasmaColorTuple
- Array of colors for the plasma blocks. Colors available in HEX and RGB formats. - speed:
number
- Speed of the plasma animation. - opacity:
number
- Opacity of the plasma blocks. - blur:
number
- Blur effect applied to the plasma blocks.
InitialPlasmaConfig
type InitialPlasmaConfig = Pick<PlasmaConfig, "blocksColors"> &
Omit<Partial<PlasmaConfig>, "blocksColors">;
- Same as
PlasmaConfig
, exceptblocksColors
is required (used inPlasmaBackground
props).
PlasmaControls
type PlasmaControls = {
changeColor: (blocksColors: PlasmaColorTuple) => void;
changeSpeed: (speed: number) => void;
changeOpacity: (opacity: number) => void;
changeBlur: (blur: number) => void;
updateConfig: (config: Partial<PlasmaConfig>) => void;
shake: (duration: number, colors?: PlasmaColorTuple) => void;
};
- changeColor:
(blocksColors: PlasmaColorTuple) => void
- Change the colors of the plasma blocks. - changeSpeed:
(speed: number) => void
- Change the speed of the plasma animation. - changeOpacity:
(opacity: number) => void
- Change the opacity of the plasma blocks. - changeBlur:
(blur: number) => void
- Change the blur effect of the plasma blocks. - updateConfig:
(config: Partial<PlasmaConfig>) => void
- Update the plasma configuration. - shake:
(duration: number, colors?: PlasmaColorTuple) => void
- Apply a shake effect to the plasma blocks.
PlasmaColorTuple
type PlasmaColorTuple = [PlasmaColor, PlasmaColor, PlasmaColor];
type HexColor = `#\${string}`;
type RgbColor = `rgb(\${number}, \${number}, \${number})`;
type PlasmaColor = HexColor | RgbColor;
- Tuple of three color strings.
UsePlasmaReturn
type UsePlasmaReturn = [PlasmaConfig, PlasmaControls];
- PlasmaConfig:
PlasmaConfig
- Configuration object for the plasma. - PlasmaControls:
PlasmaControls
- Object containing functions to control the plasma.
PlasmaRange
type PlasmaRange = [number, number];
- Simple range type where
PlasmaRange[0]
is the lowest andPlasmaRange[1]
is the highest value in the range.
PlasmaBackgroundProps
interface PlasmaBackgroundProps {
initial: InitialPlasmaConfig;
animationConfiguration?: AnimationConfig;
}
- initial:
InitialPlasmaConfig
- Initial configuration for the plasma. - animationConfiguration:
AnimationConfiguration
- Configuration for the animation.
AnimationConfig
interface AnimationConfig {
startPositions: PlasmaGradientPosition[];
block: {
widthRange: PlasmaRange;
heightRange: PlasmaRange;
};
keyframesConfig: {
skewRange: PlasmaRange;
rotateRange: PlasmaRange;
translatePercentRange: PlasmaRange;
};
}
Configuration where you can define generation ranges for different options. All metrics will be generated randomly within the provided ranges.
- startPositions:
PlasmaGradientPosition[]
- Array of starting positions for the plasma gradient (top, left CSS properties) which will be selected randomly. - block:
{ widthRange: PlasmaRange; heightRange: PlasmaRange; }
- Configuration for the block dimensions.- widthRange:
PlasmaRange
- Range for the block width. - heightRange:
PlasmaRange
- Range for the block height.
- widthRange:
- keyframesConfig:
{ skewRange: PlasmaRange; rotateRange: PlasmaRange; translatePercentRange: PlasmaRange; }
- Configuration for the keyframe animations.- skewRange:
PlasmaRange
- Range for the skew transformation. - rotateRange:
PlasmaRange
- Range for the rotation transformation. - translatePercentRange:
PlasmaRange
- Range for the translation transformation in percentage.
- skewRange:
Components
PlasmaBackground
const PlasmaBackground: ForwardRefExoticComponent<
PlasmaBackgroundProps & {
children?: ReactNode | undefined;
} & RefAttributes<UsePlasmaReturn>
>;
- exposeConfigRef:
React.RefObject<PlasmaConfig>
- Ref object to expose the plasma configuration.
Hooks
usePlasmaContext
const usePlasmaContext = (): PlasmaControls & { config: PlasmaConfig } => { ... }
- Returns:
PlasmaControls & { config: PlasmaConfig }
- The current context value for the plasma configuration and controls.
Feedback
This is my first JS library, so feel free to criticize :D. Also, I've never built something related to graphics, so if you find any issues, please refer to GitHub and create them there.
Want to discuss the library logic?
- Telegram: @kozenya390
- Discord: hjkdasfbgnc
This project was inspired by an awesome plasma background generator: https://github.com/fracergu/css-plasma-background-generator