Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/guanzo/vue-smooth-reflow

Transition an elements reflow when the data changes.
https://github.com/guanzo/vue-smooth-reflow

animation auto mixin reflow transition vue

Last synced: 3 days ago
JSON representation

Transition an elements reflow when the data changes.

Host: GitHub
URL: https://github.com/guanzo/vue-smooth-reflow
Owner: guanzo
License: mit
Created: 2018-08-18T23:31:27.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2019-04-19T12:28:11.000Z (over 5 years ago)
Last Synced: 2024-12-18T05:02:14.198Z (10 days ago)
Topics: animation, auto, mixin, reflow, transition, vue
Language: JavaScript
Size: 132 KB
Stars: 450
Watchers: 6
Forks: 18
Open Issues: 15
Metadata Files:
- Readme: README.md
- License: license.txt

Awesome Lists containing this project

README

# Vue Smooth Reflow (VSR)

A Vue mixin that transitions reflow.

When the component's data is changed, any CSS properties that you register will transition to its new value.

Common use cases are:

* Transitioning `height: auto` and `width: auto`.
* Smoothly repositioning elements.

Note that this library has no overlap with Vue's built in `` components.

## Table of Contents

* [Demo](#demo)
* [Installation](#installation)
* [Usage](#usage)
* [API](#api)
* [Smooth Component](#smooth-component)
* [Examples](#examples)

## Demo

https://vuesmoothreflow.guanzo.io

If you want to see how the examples were configured, the demo source is here: [github](https://github.com/guanzo/vue-smooth-reflow-demo)

## Installation

Download via npm:
```shell
$ npm install vue-smooth-reflow
```

Include via cdn:
```html

```

## Usage

Module:

```javascript

// The component's root el will now transition to
// accomodate new values of 'this.children'

import smoothReflow from 'vue-smooth-reflow'
export default {
mixins: [smoothReflow],
data() {
return {
children: '<Dynamic value>'
}
},
mounted(){
this.$smoothReflow()
},
}

```

Browser:

The mixin is available via the global variable `SmoothReflow`

## API

`$smoothReflow(options)`

Enables smooth reflow on an element. This method is available on the component instance.

`options` can be an object, or an array of objects.

#### Options reference

* `el`

Type: `Element | String`

Default: The components root element.

An element reference, or a CSS selector string. The resolved element will transition reflows on registered properties. This element is referred to as the "smooth element".

Use a selector string if the element is not rendered initially, like if it's hidden with `v-if`. If the selector returns multiple elements, the first one will be used.

* `property`

Type: `String | Array`

Default: `height`

Valid values: `height`, `width`, `transform`

The CSS property(s) that you want to transition. You can pass any combination.

For `transform`, VSR will only transition the `translate()` function. This is to handle element repositioning due to reflow.

* `transition`

Type: `String`

Default: `height .5s`

A valid CSS transition value. If you register multiple properties, and want different transitions for each, you can use commas.

```javascript
this.$smoothReflow({
property: ['height', 'width'],
transition: 'height .25s ease-in-out, width .75s ease-out'
})
```
The default value is conditional on the `property` option.

For example, if you register `height` and `transform` like so:

```javascript
this.$smoothReflow({
property: ['height', 'transform']
})
```

The default value will become `height .5s, transform .5s`.

If the smooth element has transitions on other properties like `background-color`, they will be preserved.

NOTE: Any transitions defined as an inline style on the smooth element will be ignored and erased.

* `transitionEvent`

Type: `Object`

Default: `null`

Valid values:
``` javascript
transitionEvent: {
// Any valid CSS selector. Note that comma delimited selectors are valid.
selector: String,
// Any valid CSS property name.
propertyName: String
}
```

Configures the smooth element to react to `transitionend` events that are emitted by other elements. You must opt-in for this behavior, there is no default.

`selector` and `propertyName` serve as filters so that the smooth element doesn't cause reflows for every `transitionend` event that it catches, which impacts performance. When the smooth element receives a `transitionend` event, it will check if `selector` matches `event.target`, and/or if `propertyName` matches `event.propertyName`. You can specify one or the other, or both. All checks must pass in order for the smooth element to proceed with the smooth reflow.

A common use case is to delay the smooth reflow until after a child element has been transitioned out with `v-if/v-show` and ``.

For example, if you want to react to any child `div` elements that transition out with opacity, use this config:

``` javascript
transitionEvent: {
selector: 'div',
propertyName: 'opacity'
}
```

Let's say you want to transition the smooth element's position. You want to wait for an element with class `.i-cause-reflow` to transition out before performing the smooth reflow. This element can be located anywhere within the component. Here's the configuration for that:

``` javascript
transitionEvent: {
selector: '.i-cause-reflow',
}
```

Check out the demo for more examples.

* `hideOverflow`

Type: `Boolean`

Default: `true`

Hides overflow during the transition.

This has 2 benefits. It prevents the scrollbar from appearing, and will hide child elements that overflow.

`$unsmoothReflow(options)`

Disables smooth reflow on an element. This method is available on the component instance.

`options` can be an object, or an array of objects.

Registered elements that have the same `el` as the passed in options will be unregistered. This usually isn't necessary, but is useful if you want to disable the behavior while the component is still alive.

## Smooth Component

Importing VSR into every component that needs it violates DRY. Instead, you can create one component that imports VSR then use it as needed. This should satisfy 90% of use cases.

Example:

```js
// SmoothReflow.vue

import smoothReflow from 'vue-smooth-reflow'
export default {
name: 'SmoothReflow',
mixins: [smoothReflow],
props: {
tag: {
type: String,
default: 'div'
},
options: Object,
},
mounted () {
this.$smoothReflow(this.options)
}
}

```

Globally register this component for convenience.

```js
// main.js
import SmoothReflow from './components/SmoothReflow'

Vue.component('SmoothReflow', SmoothReflow)
```

Update your existing components that import VSR. This is a modification of the first [usage example](#usage). Goodbye boilerplate!

```diff

-import smoothReflow from 'vue-smooth-reflow'
export default {
- mixins: [smoothReflow],
data() {
return {
children: '<Dynamic value>'
}
},
- mounted(){
- this.$smoothReflow()
- },
}

```

You may run into reactivity issues when using the `SmoothComponent`. VSR hooks into the component's `beforeUpdate` and `updated` lifecycle methods, so if those are never called, then the transition won't occur.

## Examples:

```javascript
mounted(){
// Zero config. Enables smooth reflow on this.$el
this.$smoothReflow()
// Register with element reference
this.$smoothReflow({
el: this.$refs.wrapper,
})
// Register with classname. The first match will be used.
this.$smoothReflow({
el: '.wrapper-2',
})
// Pass an array of options
this.$smoothReflow([
// Wait for .reflow-causer to emit a transitionend event,
// then transition the smooth element's position
{
el: this.$refs.wrapper,
property: 'transform',
transitionEvent: {
selector: '.reflow-causer'
}
},
// Wait for a transitionend event for opacity that
// comes from the smooth elements descendants,
// then transition the smooth elements height and width.
{
el: '.wrapper-2',
property: ['height', 'width'],
transitionEvent: {
propertyName: 'opacity'
}
},
])
// If the element reference is a component,
// make sure to pass in its "$el" property.
this.$smoothReflow({
el: this.$refs.wrapper.$el,
})
// Unregister a smooth element that would match
// the selector '.wrapper-5'
this.$unsmoothReflow({
el: '.wrapper-5'
})
}

```

### Differences from vue-smooth-height

* Enables smooth reflows on `width` and `transform`.

* VSR will no longer check for existing transition values for registered properties. It will only use the value of the `transition` option.

* The `hideOverflow` option now defaults to `true`.

* The way child transitions are handled is completely different.

## License

[MIT](http://opensource.org/licenses/MIT)