![QUIQQER Animate](bin/images/Readme.jpg)

# QUIQQER Animate

QUIQQER Animate provides CSS animations and configurable reveal effects that
start when elements enter the viewport.

The bundled animation library is based on
[Animate.css](https://github.com/animate-css/animate.css) and retains its
legacy class names for compatibility with existing QUIQQER projects.

## Features

- CSS classes for general-purpose animations
- Viewport-based fade and slide animations
- Configurable CSS selectors for scroll effects
- Themeable duration, easing, fill mode and movement offset
- Support for the `prefers-reduced-motion` accessibility preference

## Installation

The package name is

```shell
quiqqer/animate
```

## Configuration

The project settings contain an **Animations** category with the following
options:

| Setting | Description |
| --- | --- |
| `animate.general.enableAnimationLibrary` | Loads the bundled `animate.min.css` animation library. |
| `animate.scroll.enable` | Enables viewport-based scroll animations. |
| `animate.scroll.skipAnimationIfVisible` | Skips animations for elements already visible during initialization. |
| `animate.scroll.fadeIn` | Additional selectors for the plain fade-in effect. |
| `animate.scroll.fadeinFromDown` | Additional selectors that fade in from below. |
| `animate.scroll.fadeinFromLeft` | Additional selectors that fade in from the left. |
| `animate.scroll.fadeinFromRight` | Additional selectors that fade in from the right. |

The `fadeinFromDown` spelling is retained for backward compatibility. It maps
to the `bottom` effect in the JavaScript configuration.

## Usage

### Animation library

Add `animated` and an animation class to an element:

```html
<div class="animated fadeIn">
    This content fades in.
</div>
```

Existing projects can continue using the legacy Animate.css class names
provided by `bin/animate.min.css`.

### Scroll animations

Enable scroll animations in the project settings and use one of the standard
classes:

```html
<section class="fade-in">
    Fades in when it enters the viewport.
</section>

<section class="fade-in-from-bottom">
    Fades in from below.
</section>

<section class="fade-in-from-left">
    Fades in from the left.
</section>

<section class="fade-in-from-right">
    Fades in from the right.
</section>
```

The legacy aliases `.fadein-from-*` and `.fadeIn-from-*` remain supported.
Elements can also be selected without changing their markup by entering
comma-separated CSS selectors in the project settings.

The additional `.fade-in-from-top` effect can be used with the `.js-scroll`
marker:

```html
<section class="js-scroll fade-in-from-top">
    Fades in from above.
</section>
```

## CSS variables

Set the variables on the animated element or in project/theme CSS:

| Variable | Default | Purpose |
| --- | --- | --- |
| `--qui-animate-scroll-animation-duration` | `750ms` | Animation duration |
| `--qui-animate-scroll-animation-easing` | `ease-in-out` | Timing function |
| `--qui-animate-scroll-animation-fill-mode` | `both` | Animation fill mode |
| `--qui-animate-scroll-offset` | `30px` | Initial movement distance |
| `--qui-animate-scroll-animation-name` | Effect-specific | Overrides the selected animation |

Example:

```css
.project-teaser {
    --qui-animate-scroll-animation-duration: 1s;
    --qui-animate-scroll-animation-easing: ease-out;
    --qui-animate-scroll-offset: 3rem;
}
```

## Reduced motion

When the operating system reports `prefers-reduced-motion: reduce`, scroll
animations are disabled and affected elements are shown immediately. No
additional project configuration is required.

## Development

- [Project and source code](https://dev.quiqqer.com/quiqqer/plugin-animate)
- [Work items](https://dev.quiqqer.com/quiqqer/plugin-animate/-/work_items)
- [Wiki](https://dev.quiqqer.com/quiqqer/plugin-animate/-/wikis/home)

## Support

For support, contact [support@pcsg.de](mailto:support@pcsg.de).

## License

MIT
