illusory

Seamlessly morph one element into another. Demo

Contents

• Installation
• Basic usage
• API Details
  • illusory(from, to [, options]): Promise
  • IllusoryElement(el [, options])
    • Properties
    • Methods
• Contributing
  • Setup
  • Development
    • Building
    • Live-reload server
  • Testing
    • Running tests
  • /docs page

Installation

<!-- For IE support -->
<script src="https://cdn.jsdelivr.net/npm/es6-promise@4/dist/es6-promise.auto.min.js"></script>

<script src="https://unpkg.com/illusory"></script>

<script>
  illusory(from, to)
</script>

or

$ npm install illusory

import { illusory } from 'illusory'

Basic usage

illusory(from, to)

API Details

See the docs page for an introduction with examples.

illusory(from, to [, options]): Promise

• from — an Element or an IllusoryElement
• to — an Element or an IllusoryElement
• options — Object (see table below)

Important
Options that are also available for IllusoryElement will not apply to IllusoryElements when passed to illusory
For example:
In the following snippet, from will include all of its children because includeChildren defaults to true. However, to will not include its children.

const from = new IllusoryElement(el)

const to = document.querySelector('#to')

illusory(from, to, {
  includeChildren: false
})

IllusoryElement(el [, options])

• el — Element
• options — Object (see table below)

Properties

• natural: Element — The original element.
• clone: Element — The clone of the "natural" element.
• rect: DOMRect — The bounding box of the "natural" element.

Methods

• setStyle(property: string, value: string) — Sets the given css style on the cloned element.

  Changes made using this method will not be reflected by getStyle.

  // If the background is white
  illusoryEl.clone.style.backgroundColor // #fff
  // And we set it to black with `getStyle`
  illusoryEl.setStyle('backgroundColor', '#000')
  // The color will be reflected be the DOM
  illusoryEl.clone.style.backgroundColor // #000
  // But not by `getStyle`. It will still return white
  illusoryEl.getStyle('backgroundColor') // #fff

• getStyle(property: string): string — Returns the orignal style value for the given property.

  Note: Because window.getComputedStyle is used under the hood, CSS shorthand properties are not supported (background, border-radius, etc.). Instead use background-color, background-image, border-bottom-right-radius, etc.

• waitFor(property: string): Promise —
  Returns a Promise that resolves when the cloned element emits a "transitionend" event for the given property.
  If "any" is passed, the promise will resolve on the first "transitionend" regardless of the transitioned property.

• hide() — Hides the cloned element

• show() — Shows the cloned element

• hideNatural() — Hides the natural element

• showNatural() — Shows the natural element

• flushCSS() — Forces the browser to apply any style changes that might be queued.

  Useful for applying any css changes before setting a transition on the element.

• detach() — Removes the clone and cleans up styles applied to the natural element.

Contributing

Setup

$ git clone https://github.com/justintaddei/illusory
$ cd illusory
$ npm install

Development

Building

$ npm run build

# Watch mode
$ npm run dev

Live-reload server

$ npm run serve

Testing

Tests should be written in the same folder as the file being tested.
Use the [filename].spec.ts naming convention.

Running tests

$ npm test

/docs page

# Transpile ./docs/index.js
$ npm run build:docs

# Watch ./docs/index.js and build on save.
$ npm run dev:docs