Animations are a powerful tool that can enhance the user experience on a website. When used correctly, they can make a website more engaging, interactive, and intuitive. In this article, we will explore the animations library for SwifWeb.

I’m talking about the most famous animate.css library. Let’s install it and take a look at how to use it!

Installation

If you are new to SwifWeb please take a look how to create new project in this article.

In the project open Package.swift and edit the dependencies section to make it look like this:

dependencies: [
    // the rest of the other dependencies including swifweb/web
    .package(
        url: "https://github.com/swifweb/animate",
        from: "1.0.0"
    ),
]

Next edit executableTarget to make it look like this:

.executableTarget(name: "App", dependencies: [
    .product(name: "Web", package: "web"),
    .product(name: "Animate", package: "animate")
]),

Then open App.swift add import Animate and configure it in didFinishLaunching method like this:

Lifecycle.didFinishLaunching {
    Animate.configure()
}

Usage

All the classes from the original library are under the hood, and for SwiftWeb users, a very convenient and beautiful Swift interface is available.

Take any element and add an animation to it that will be launched once it is added to the DOM.

@DOM override var body: DOM.Content {
    Img()
        .src("https://i.ytimg.com/vi/1Ne1hqOXKKI/maxresdefault.jpg")
        .width(400.px)
        .animate(.jello) // <- here we added jello animation
}

Or take any element on the screen and add an animation to it on-the-fly:

lazy var img = Img()

@DOM override var body: DOM.Content {
    self.img
        .src("https://i.ytimg.com/vi/1Ne1hqOXKKI/maxresdefault.jpg")
        .width(400.px)
    Button("Animate").onClick {
        self.img.animate(.jello) // <- here we animate
    }
}

Additionally, you can set duration, delay, and repeat settings.

.animate(.jello, delay: 0, duration: 1, repeat: 0)

All these parameters are optional. Values will be removed automatically when the animation ends.

Alternatively these options can be set using separate methods:

.animateDelay(0)
.animateDuration(1)
.animateRepeat(0)

And you also should remove these values manually:

.removeAnimateDelay()
.removeAnimateDuration()
.removeAnimateRepeat()

Let’s talk more about each option.

Delay

Predefined convenience values:

.delay0s // animation starts immediately
.delay1s // adds a 1-second delay
.delay2s // adds a 2-second delay
.delay3s // adds a 3-second delay
.delay4s // adds a 4-second delay
.delay5s // adds a 5-second delay

Create your own convenience value in the extension:

extension DelayValue {
    static var delay10s: Self { 10 } // adds a 10-second delay
}

Or you can use any Float or Int value as in the examples above.

Duration

Predefined convenience values:

.slow   // executes animation for 2 seconds
.slower // executes animation for 3 seconds
.fast   // executes animation for 0.8 seconds
.faster // executes animation for 0.5 seconds

Create your own convenience value in the extension:

extension DurationValue {
    static var verySlow: Self { 5 } // executes animation for 5s
}

Or you can use any Float or Int value as in the examples above.

Repeat

Predefined convenience values:

.repeat1  // repeats animation once
.repeat2  // repeats animation twice
.repeat3  // repeats animation three times
.infinite // repeats animation infinitely

Create your own convenience value in the extension:

extension RepeatValue {
    static var repeat5: Self { 5 } // repeats animation five times
}

Or you can use any Int value as in the examples above.

Example with convenience values

.animate(.jello, delay: .delay0s, duration: .slower, repeat: .repeat2)

And separate methods:

.animateDelay(.delay0s)
.animateDuration(.slower)
.animateRepeat(.repeat2)

Best Practices

Animations can significantly enhance a user's experience with a web interface. However, it is essential to follow some guidelines to ensure that the experience is not negatively impacted. By adhering to the following rules, you can create a positive start.

Use meaningful animations

Animations should convey a clear intention, rather than just being decorative. Avoid using attention-seeking animations solely for their flashiness; instead, use them to highlight something special in the interface. Use entrance and exit animations to orient the user to the interface and signal a transition to a new state.

Playfulness is good, but be mindful

Adding playfulness to an interface can be beneficial, but ensure that the animations are not obstructing the user's experience or impacting the page's performance due to overuse.

Avoid animating large elements

Animating large elements can lead to a poor user experience, causing confusion and making the animations appear jittery. Therefore, it is advisable to avoid animating large elements, as they add little value to the user.

Avoid infinite animations

While animate.css provides utility classes for repeating animations, including infinite ones, it's recommended to avoid endless animations. These animations can distract users and annoy them, resulting in a negative experience. Therefore, use them wisely!

Gotchas

You can't animate inline elements

Animating inline elements is not recommended according to the CSS animation specifications and may not work on all browsers. block or inline-block level elements, including grid and flex containers and their children, should be animated instead. To animate an inline-level element, you can set its display property to inline-block.

Overflow

When animating elements across the screen, some Animate.css animations may create scrollbars on your webpage. To avoid this, you can use the overflow: hidden property in the parent element containing the animated element. However, there is no definitive recipe for when or how to use it.

Intervals between repeats

It is not currently possible to set intervals between repeats using pure CSS.

But it is possible using `.animationEnd` event listener:

Img()
    .src("https://i.ytimg.com/vi/1Ne1hqOXKKI/maxresdefault.jpg")
    .width(400.px)
    .animate(.jello, delay: 0, duration: 2)
    .addEventListener(
        .animationEnd,
        options: .init(once: true)
    ) { event, element in
        Dispatch.asyncAfter(0.5) {
            element.animate(.jello, delay: 0, duration: 2)
        }
    }

Or even more convenient:

Img()
    .src("https://i.ytimg.com/vi/1Ne1hqOXKKI/maxresdefault.jpg")
    .width(400.px)
    .animate(.jello, delay: 0, duration: 2) { element in
        Dispatch.asyncAfter(0.5) {
            element.animate(.jello, delay: 0, duration: 2)
        }
    }

That’s All

Yeah, that library is compact but powerful!

Wanna learn more? Stay tuned for the upcoming articles!