matrix-rain

matrix-rain is a library for generating customizable matrix rain effects. It comes with a built-in React component for ease of use, but you can use it without React if you want.

Installation

npm install @ojdom/matrix-rain

Usage

The library exports 2 files:

• Matrix - a React component
• MatrixController - a class that handles the functionality.

When not using React, you will only need to import the MatrixController

Create a MatrixController object and pass it the desired options.

• Using React? Pass the MatrixController object to the React component as a prop. Make sure that the controller isn't replaced when the component is re-rendered!
• Not using React? You will have to set a canvas element on the MatrixController. You can do this through the constructor or through the setCanvas() method.

Documentation

The MatrixController class has a number of methods that you can use to control the rain effect:

• start() - starts the rain effect
• disable() - disables the rain effect
• stop() - stops the rain effect immediately

These methods will only work if a canvas has been set. When using the React component, this will be done automatically. When not using React, you will have to set a canvas element yourself. You can do this through the setCanvas() method or through the constructor.

The MatrixController constructor takes two arguments, both of which are optional:

1. options - an object containing the desired options. Refer to the options section below for a list of available options.
2. canvas - a canvas element. If this is omitted, the canvas will have to be set manually through the setCanvas() method.

Dimensions

The dimensions of the canvas are determined by the dimensions of its' container. When using the React component, you will need to pass the width and height of the container to the component as props.

When not using React, the canvas will automatically resize itself to the dimensions of its' container. Avoid padding on the canvas container!

React Component

The Matrix component has 3 required props:

• controller - the MatrixController object to use
• width - the width of the canvas
• height - the height of the canvas

It also has 2 optional props:

• auto - whether or not to automatically start the rain effect when the component is mounted. Defaults to false.
• indicators - whether or not to show rudimentary control buttons. Defaults to false.

Options

The options object can contain the following options:

• colors - an object containing 3 different values:
  • background - the canvas background color. Defaults to '#000'.
  • primary - the character color. Defaults to 'rgb(55, 255, 55)'.
  • flashed - the color of the character when it first appears. Defaults to '#fff'.
• fontSize - the font size of the rain text. Defaults to 20.
• fontFamily - the font family of the rain text. Defaults to 'roboto'.
• chars - the characters to use in the rain text. Defaults to 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456789@#$%^&()&^%+-/~{[|`]}'.
• animationSpeed - the speed at which the rain animation occurs. Recommended range is 10-30. Defaults to 12.
• dropPercentage - the percentage of the canvas that should be covered with rain. Recommended range is 10-75. Defaults to 25.
• charChangeRate - the rate at which the characters change. Recommended range is 0-20. Defaults to 16.
• opacityChangeRate - the rate at which the character opacity changes. Recommended range is 0-20. Defaults to 4.
• fadedPercentage - the percentage of characters that should be faded. Recommended range is 0-50. Defaults to 25.
• hiddenPercentage - the percentage of characters that should be hidden. Recommended range is 0-50. Defaults to 25.

Omitting part of the options object will result in the default value being used. Omitting the options object entirely will result in all default values being used.

Roadmap

• Storybook is coming soon(tm).
• Type support will come eventually.
• Other functionality may be added in the future.