# solutions-flickerlessly

**Repository Path**: mirrors_adobe/solutions-flickerlessly

## Basic Information

- **Project Name**: solutions-flickerlessly
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-03-12
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flickerlessly.js

Flickerlessly is a tiny JavaScript library that helps detecting any specified HTML element as soon as it appears on the page. It is one of the most performant ways for DOM element detection thanks to the `keyframes` animation technique. This approach successfully replaces the DOM polling with `setTimeout`/`setInterval` that drains device resources or `MutationObserver` that has browser limitations and may be a less performant solution. 

## How Flickerlessly Works

Behind the scenes, Flickerlessly is subscribing to DOM `animationstart` events. During initialization all specified CSS selectors are assigned to `keyframes` animation rules. Once specified elements appear in the DOM, animation is triggered and JavaScript event listener receives a notification to trigger a specified callback function for particular selectors. 

## Example of Usage

```
Flickerlessly.onReady({
    selector: '.a, .b', 
    success: function(el, log){
        log("Detected element", el);
    }},
    {selector: '.c', 
    success: myCallbackFn, 
    persist: true 
});
```

## Documentation

`Flickerlessly.onReady([object1, object2, objectN])` is the only available initializer method.

The object in the Array list of arguments has the following structure:
 
| Name                    | Type     | Required | Default | Description                                |
|-------------------------|----------|----------|---------|--------------------------------------------|
| selector                | String   | Yes      | None    | CSS selector(s) to be detected             |
| success                 | Function | Yes      | None    | Callback to execute after element detected | 
| persist                 | Bool     | No       | false   | Executes the callback again if true        | 

`selector` can be any CSS selector or list of selectors: `.myClass` or `body > p, #myElement`, etc.

`success` is a custom callback function. It passes detected element and custom logger in the arguments:
```
success: function(el, log){
    log("Detected element", el);
}}
```

`persist` is a Boolean that indicates whether the above callback function needs to be executed again, when set to true, or suppressed for every following new `keyframe` animation. Why would animation occur more than once? Since we are using `keyframe` animations for specified elements, animations are triggered every time this element is is touched by DOM tree (for example, child is appended inside). 

## Why Flickerlessly?

Creation of Flickerlessly was inspired to find a better DOM polling solution to be used in Adobe Target HTML offers where detection of elements is required to perform any DOM manipulations. But Flickerlessly can be used for any scenarios where DOM detection is needed.

### Contributing

Contributions are welcomed! Read the [Contributing Guide](CONTRIBUTING.md) for more information.

### Licensing

This project is licensed under the MIT License. See [LICENSE](LICENSE) for more information.