Arctic Landscape is an animated [React][] [SVG][mdn-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”][wiki-aurbor] (also called _northern lights_) uses a gentle gradient animation to imitate the shimmering light.
Next to the main [animation poses](#animation-pose) the component can be customized in aspects like the [total animation duration](#animation-duration) and [styles of the outlines](#additional-outlines-styles).
A callback function can be passed to be called when the [draw/erase animation has been completed](#animation-completion-callback).
It also allows to use a [custom SVG `` element for the _Aurora Borealis_ shimmering light](#aurora-borealis-gradient) effect.
The component is build and compatible with the awesome [styled-components][stc] and [React Pose][rp] projects.
It was mainly developed for the usage and integration with [Nord][], therefore all default colors are based on [Nord's color palettes][nord-docs-c].
## Quick Start
```sh
npm install --save react react-dom arctic-landscape styled-components react-pose
```
## Getting Started
### Installation
Add the package as dependency to your project:
```sh
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][npm-stc] and [react-pose][npm-rp]** packages that are defined as [peer dependencies][nodejs-blog-peerdeps] and must be installed separately like described in the [peer dependencies](#peer-dependencies) section below.
#### Peer Dependencies
This package uses [Styled Components][stc-doc-api] and [React Pose][rp-doc-api] API functions that return [React][] components.
Therefore, next to [React][npm-r] and [React DOM][npm-rd], this package depends on the [styled-components][npm-stc] and [react-pose][npm-rp] packages defined as [peer dependencies][nodejs-blog-peerdeps].
Linux & macOS users can easily install all peer dependencies by using [npx][npm-npx], [introduced in `npm@5.2.0`][npm-blog-npx], which comes [pre-bundled with **Node.js 8.2.0** or higher][npm-get]:
```sh
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][npm-ipd] package locally/globally to let it handle the installation of all peer dependencies.
```sh
# 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:
```sh
# 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][mdn-export] React component `ArcticLandscape`.
```js
import React, { Component } from "react";
import ArcticLandscape from "arctic-landscape";
```
The component can now be placed somewhere in the render tree:
```jsx
// Within a simple function component…
const CustomFunctionComponent = props => (
);
// …or a class component.
class CustomFunctionComponent extends Component {
/* ... */
render() {
return (
);
}
}
```
**NOTE**: The component itself **doesn't define any sizing attributes** and inherits from the parent element like the `
` 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][r-docs-comp] and store the name of the current pose in the state that can be toggled through a function:
```jsx
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 (
);
}
}
```
Make sure to read the [React Pose documentation][rp-docs-gs] 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][wiki-aurbor] that is filled with an animated [`` element][mdn-svg-lg] to imitate the shimmering light. It can be swapped out with another `` element by passing the ID of this element to the `auroraBorealisGleamGradientId` prop.
```js
```
### Animation Duration
> **Prop**: `duration`
> **Type**: number
> **Default**: `4000`(ms)
> **Required**: No
The total animation duration in milliseconds.
```js
```
### Animation Completion Callback
> **Prop**: `onAnimationComplete`
> **Type**: function
> **Default**: `() => {}`(noop)
> **Required**: No
The function that will be called when the pose animation has been completed.
```js
const handleAnimationCompletion = () => console.log("Arctic Landscape pose animation has been completed!");
;
```
### Additional Outlines Styles
> **Prop**: `outlineStyles`
> **Type**: [`css` object][stc-doc-api-css] or [style object][stc-doc-adv-sto]
> **Default**: `() => {}` (noop)
> **Required**: No
Allows to pass additional styles for all outlines of the vector graphic. Since Arctic Landscape is built with [styled-components][stc] this prop accepts either a object of the [`css`][stc-doc-api-css] API function or [style object][stc-doc-adv-sto].
```js
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"
};
;
```
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][mdn-export]:
- `POSE_DRAW` — The name of the `draw` animation pose
- `POSE_ERASE` — The name of the `erase` animation pose
```js
import { POSE_DRAW, POSE_ERASE } from "arctic-landscape";
```
**NOTE**: The custom `` 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 [`` element][mdn-svg-lg] which \*\*must be placed within a [`` element][mdn-svg-defs], 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 `
