arctic-landscape

An animated drawing of an arctic landscape

Arctic Landscape is an animated React SVG component with a flat, simple and elegant appearance.

It consists of lines that should convey the effect to be drawn by hand and fade-in fillings that are smoothly timed on each other. The “Aurora Borealis” (also called northern lights) uses a gentle gradient animation to imitate the shimmering light.

Next to the main animation poses the component can be customized in aspects like the total animation duration and styles of the outlines. A callback function can be passed to be called when the draw/erase animation has been completed. It also allows to use a custom SVG <linear-gradient> element for the Aurora Borealis shimmering light effect.

The component is build and compatible with the awesome styled-components and React Pose projects. It was mainly developed for the usage and integration with Nord, therefore all default colors are based on Nord's color palettes.

Quick Start

npm install --save react react-dom arctic-landscape styled-components react-pose

Getting Started

Installation

Add the package as dependency to your project:

npm install --save arctic-landscape

Run npm install from within the project root to bootstrap the project and install the development- and runtime dependencies. Note that this will not install the required styled-components and react-pose packages that are defined as peer dependencies and must be installed separately like described in the peer dependencies section below.

Peer Dependencies

This package uses Styled Components and React Pose API functions that return React components.

Therefore, next to React and React DOM, this package depends on the styled-components and react-pose packages defined as peer dependencies.

Linux & macOS users can easily install all peer dependencies by using npx, introduced in npm@5.2.0, which comes pre-bundled with Node.js 8.2.0 or higher:

npx install-peerdeps arctic-landscape

When using npm < 5.2.0, npx is not pre-bundled, but users can either simply install it globally and then run the above command or install the install-peerdeps package locally/globally to let it handle the installation of all peer dependencies.

# Via local installation… 
npm install install-peerdeps
./node_modules/.bin/install-peerdeps arctic-landscape
 
# …or globally. 
npm install -g install-peerdeps
install-peerdeps arctic-landscape

Manually

All peer dependencies can also be installed manually (e.g. for users running a Microsoft Windows based system) by installing the correct version of each package:

# Show a list of all required peer dependencies 
npm info "arctic-landscape@latest" peerDependencies
 
# Install all required peer dependencies 
npm install --save arctic-landscape react react-dom react-pose styled-components

Usage

Arctic Landscape can be used by importing the default exported React component ArcticLandscape.

import React, { Component } from "react";
import ArcticLandscape from "arctic-landscape";

The component can now be placed somewhere in the render tree:

// Within a simple function component…
const CustomFunctionComponent = props => (
  <div>
    <ArcticLandscape pose="erase" {...props} />
  </div>
);
 
// …or a class component.
class CustomFunctionComponent extends Component {
  /* ... */
  render() {
    return (
      <div>
        <ArcticLandscape pose="erase" />
      </div>
    );
  }
}

NOTE: The component itself doesn't define any sizing attributes and inherits from the parent element like the <div> in the example above. Therefore it must be wrapped in a container to control the width and height of the component.

To trigger the animation change the passed erase animation pose to the draw animation, e.g. by using a class-based component and store the name of the current pose in the state that can be toggled through a function:

import React, { Component } from "react";
import ArcticLandscape, { POSE_DRAW, POSE_ERASE } from "arctic-landscape";
 
class CustomFunctionComponent extends Component {
  state = {
    pose: POSE_ERASE
  };
 
  togglePose = () => this.setState(({ pose }) => ({ pose: pose === POSE_ERASE ? POSE_DRAW : POSE_ERASE }));
 
  render() {
    const { pose } = this.state;
 
    return (
      <div>
        <button onClick={this.togglePose}>Toggle Animation Pose</button>
        <ArcticLandscape pose={pose} />
      </div>
    );
  }
}

Make sure to read the React Pose documentation for more details if you're not already familiar with the animation concept with poses.

Customization

The component can be customized through props. All available props are documented in more detail in the sections below.

Aurora Borealis Gradient

Prop: auroraBorealisGleamGradientId
Type: string
Default: arctic-landscape-aurora-borealis-gleam
Required: No

The component renders a Aurora Borealis that is filled with an animated <linear-gradient> element to imitate the shimmering light. It can be swapped out with another <linear-gradient> element by passing the ID of this element to the auroraBorealisGleamGradientId prop.

<ArcticLandscape auroraBorealisGleamGradientId="custom-gradient-element-id" />

Animation Duration

Prop: duration
Type: number
Default: 4000(ms)
Required: No

The total animation duration in milliseconds.

<ArcticLandscape pose="erase" duration={3200} />

Animation Completion Callback

Prop: onAnimationComplete
Type: function
Default: () => {}(noop)
Required: No

The function that will be called when the pose animation has been completed.

const handleAnimationCompletion = () => console.log("Arctic Landscape pose animation has been completed!");
 
<ArcticLandscape pose="erase" onAnimationComplete={handleAnimationCompletion} />;

Additional Outlines Styles

Prop: outlineStyles
Type: css object or style object
Default: () => {} (noop)
Required: No

Allows to pass additional styles for all outlines of the vector graphic. Since Arctic Landscape is built with styled-components this prop accepts either a object of the css API function or style object.

import { css } from "styled-components";
 
// Either use the `css` API…
const additionalCssStyles = css`
  stroke-width: 1;
  stroke: #5e81ac;
`;
 
//…or a simple style object.
const additionalObjectStyles = {
  strokeWidth: 1,
  stroke: "#5e81ac"
};
 
<ArcticLandscape pose="erase" outlineStyles={additionalCssStyles} />;

Note that this will override the styles of all outlines!

Animation Pose

Prop: pose
Type: string
Default: -
Required: Yes
Values: draw|erase

The pose prop is currently the only required prop and defines the name of the actual animation pose. This can either be draw or erase where the first one starts the drawing animation and makes the component visible while the second one "erases" all drawn lines and fillings again with a quick reverted animation of the draw pose.

Note that both animation pose names are also available as constants as named exports:

• POSE_DRAW — The name of the draw animation pose
• POSE_ERASE — The name of the erase animation pose

import { POSE_DRAW, POSE_ERASE } from "arctic-landscape";

NOTE: The custom <linear-gradient> element must be available in the DOM where the component is rendered in, otherwise the element with the given ID won't be rendered! Also make sure to follow the SVG specification for the custom <linear-gradient> element which **must be placed within a <defs> element, otherwise it won't be recognized in the DOM.

For example, if you'd like to use a custom gradient with different colors, define a new <svg> element or React component and place the custom <linear-gradient> element in it, wrapped by a <defs> element. Afterwards make sure to give it a unique ID (custom-gradient-element-id in the example above) to be passed to the auroraBorealisGleamGradientId prop and render it in the same DOM like the ArcticLandscape component.

CustomAuroraBorealisGradient.jsx

const CustomAuroraBorealisGradient = () => (
  <svg>
    <defs>
      <linearGradient id="custom-gradient-element-id" x1="50%" x2="50%" y1="0%" y2="100%">
        <stop offset="0%" stopColor="#d08770">
          <animate
            attributeName="stop-color"
            dur="4s"
            repeatCount="indefinite"
            // values="#d08770; #ebcb8b; #d08770"
          />
        </stop>
        <stop offset="50%" stopColor="#ebcb8b">
          <animate attributeName="stop-color" dur="4s" repeatCount="indefinite" values="#ebcb8b; #a3be8c; #ebcb8b" />
        </stop>
        <stop offset="100%" stopColor="#a3be8c">
          <animate attributeName="stop-color" dur="4s" repeatCount="indefinite" values="#a3be8c; #b48ead; #a3be8c" />
        </stop>
      </linearGradient>
    </defs>
  </svg>
);
 
export default CustomAuroraBorealisGradient;

App.jsx

import React, { Fragment } from "react";
import ArcticLandscape from "arctic-landscape";
import CustomAuroraBorealisGradient from "./CustomAuroraBorealisGradient";
 
const App = () => (
  <Fragment>
    <CustomAuroraBorealisGradient />
    <ArcticLandscape pose="erase" auroraBorealisGleamGradientId="custom-gradient-element-id" />
  </Fragment>
);
 
export default App;

The default <linear-gradient> element is implemented in the GleamGradient component.

Development Workflow

Run npm install from within the project root to bootstrap the project and install the development- and runtime dependencies.

The project is configured for the opinionated code formatter Prettier which provides integration support for many editors to e.g. automatically format the source file on save.

Building

A distribution build can be created with Rollup by running

npm run build

Continuous integration builds are running at Circle CI.

Testing

Linting

JavaScript sources are linted with ESLint using the arcticicestudio configuration which can be run with

npm run lint:js

Markdown sources are linted with remark-lint using the arcticicestudio-preset which can be run with

npm run lint:md

All linting tasks can be run with

npm run lint

Contributing

Read the contributing guide to learn about the development process and how to propose enhancement suggestions and report bugs, how to submit pull requests and the project's styleguides, branch organization and versioning model.

The guide also includes information about minimal, complete, and verifiable examples and other ways to contribute to the project like improving existing issues and giving feedback on issues and pull requests.

---

Copyright © 2019-present Arctic Ice Studio & Sven Greb