animated-size v3.0.1

AnimatedSize

Introduce

This component provide flexible size-change animation for html element under react-dom framework.

Feature

1. AnimatedSize provide the features that let element's width/height animate between auto and any size.
2. Animation is provided by css transition so the component take less js-runtime compared with pure js implement.
3. And AnimatedSize support perfect animation that you can stop animation or change animation dest or change animation duration at any time even AnimatedSize is animating or nested element's size is changing.

• nested AnimatedSize is also fine.

• most of the job is html renderer paint, more animation with less js-runtime.

Install

npm i animated-size

Import

import { AnimatedSize } from "animated-size";

Use

const [open, setOpen] = React.useState(true);
...
<AnimatedSize widthFactor={open ? { size: "auto" } : { size: 0 }}>
  {/* your element*/}
</AnimatedSize>;

Size Factor

export type Factor = {
  size?: SizeFactor /* default: undefined */;
  duration?: number /* unit: ms, default: 350 */;
  delay?: number /* unit: ms, default: 0 */;
  curve?: DataType.EasingFunction /* default: ease */;
};

export type SizeFactor = number | string | "auto" | undefined;

For example: element's width is 150px.

<AnimatedSize widthFactor={/* set your factor */}>
  {/* if the entirely width (wrapper by span) is 150px */}
  <Element0 />
  <Element1 />
</AnimatedSize>

This width property of inline style sheet:

Factor change behaviors:

• use auto or undefined for better performance when nested element may change its size.

Custom animation curve

AnimatedSize implement the animation that underlay is css transition. Setup factor other properties to custom your animation curve as well as duration and delay just like css transition.

<AnimatedSize
  widthFactor={{
    size: "auto",
    curve: "ease-in",
    duration: 200 /* unit: ms */,
    delay: 200 /* unit: ms */,
  }}
>
  <div>{/* your components */}</div>
  <div>{/* your components */}</div>
  {/* your other components */}
</AnimatedSize>

Custom wrapper

<AnimatedSizeBuilder
  widthFactor={/* set your factor */}
  heightFactor={/* set your factor */}
  builder={(ref) => (
    <div ref={ref}>{/* pass ref to dom element that let AnimatedSize access the element object. Should be the only one dom child of AnimatedSizeBuilder. */}
    {/* set your components that wrapper by div */}
    </div>
  )}
/>

• AnimatedSize require wrapper dom element reference for calculation of this nested elements' total size

Inner element position

By default, AnimatedSize use flex layout (and center inner element) and the inner element follow the flex layout. Change the parament axisDirection, mainAxisPosition and crossAxisPosition to custom your element position. Or directly set inline style sheet -- style parament. Be careful when you use AnimatedSizeBuilder. AnimatedSize require its direct child has its own Block formatting context(BFC). The children of flex will create their own BFC automatically. It is the reason why AnimatedSize default display is flex. Reference Block formatting context. By the way, by default AnimatedSize set overflow as hidden. Set style to override it if necessary.

<AnimatedSize
  widthFactor={/* set your factor */}
  heightFactor={/* set your factor */}
  axisDirection="column"
  mainAxisPosition="start"
  crossAxisPosition="end">
  {/* your element */}
</AnimatedSize>

• axisDirection - CSSProperties.flexDirection
• mainAxisPosition - CSSProperties.justifyContent
• crossAxisPosition - CSSProperties.alignItems

<AnimatedSize
  widthFactor={/* set your factor */}
  heightFactor={/* set your factor */}
  style={{
    overflow: 'visible',
    display:'flex', /* use flex as possible as you can, block usually do not work well */
    position:'relative',
    /* Don't override width or height or transition if you want animation to work properly */
    }}>
  {/* your element */}
</AnimatedSize>

• style

Interactive Demo

git clone https://github.com/JohnGu9/AnimatedSize.git
cd AnimatedSize
npm i
npm run storybook

Browser requirement

ResizeObserver support

Component dependencies

• react-dom
• react-ref-composer

Issue report

https://github.com/JohnGu9/AnimatedSize/issues

Caution

Before version 3.0.0, the build target is es5.

After version 3.0.0, the build target is esnext. You should use some bundle tool to help your bundle this project code into your own project (like esbuild). Set your tsconfig file "module": "ESNext" and build system (like vite config file build.target) to convert your code to target platform compatible code.

Why esnext? Using esnext to compile this project and preform minimal transpiling. This can product less redundant code and reduce the package size for download.

LICENSE

MIT