arctic-landscape

    0.1.0 • Public • Published

    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

    Install

    npm i arctic-landscape

    DownloadsWeekly Downloads

    10

    Version

    0.1.0

    License

    MIT

    Unpacked Size

    598 kB

    Total Files

    13

    Last publish

    Collaborators

    • arcticicestudio