@react-md/transition

Index

Type aliases

Variables

Functions

Type aliases

CSSTransitionClassNames

CSSTransitionClassNames: string | Readonly<CSSTransitionClassNamesObject>

remarks: @since 4.0.0

FixedPositioningTransitionCallbacks

FixedPositioningTransitionCallbacks: Pick<TransitionCallbacks, "onEnter" | "onEntering" | "onEntered" | "onExited">

remarks: @since 4.0.0

TransitionEnterHandler

TransitionEnterHandler: (appearing: boolean) => void

Type declaration

- (appearing: boolean): void
- This function is called at each "enter" TransitionStage. If a TransitionOptions.nodeRef was provided, the DOM node should be available in nodeRef.current by this point if the transition requires DOM calculations.
  
  remarks
  @since 4.0.0
  
  Parameters
  - appearing: boolean
    
    Boolean if this is the initial appear flow.
  Returns void

TransitionExitHandler

TransitionExitHandler: () => void

Type declaration

- (): void
- THis function is called at each "exit" TransitionStage. If a TransitionOptions.nodeRef was provided, the DOM node should be available in nodeRef.current by this point if the transition requires DOM calculations.
  
  remarks
  @since 4.0.0
  
  Returns void

TransitionScrollCallback

TransitionScrollCallback<FixedToElement, FixedElement>: (event: Event, data: Readonly<FixedPositioningScrollData<FixedToElement, FixedElement>>) => void

Type parameters

FixedToElement: HTMLElement

An HTMLElement type for the static element.
FixedElement: HTMLElement

An HTMLElement type for the fixed element.

Type declaration

- (event: Event, data: Readonly<FixedPositioningScrollData<FixedToElement, FixedElement>>): void
- This function is called when the page is scrolled while the fixed element is visible. This is generally used to reposition the fixed element or hide it if it is no longer visible within the viewport.
  
  remarks
  @since 4.0.0
  
  Parameters
  - event: Event
    
    The scroll event
  - data: Readonly<FixedPositioningScrollData<FixedToElement, FixedElement>>
    
    The FixedPositioningScrollData that can be used for custom scroll behavior.
  Returns void

TransitionStage

The way the transition works is by flowing through the different stages and assigning waiting for a timeout to occur. Setting the stage to enter will begin the enter transition going from enter -> entering -> entered while setting the stage to exit will transition from exit -> exiting -> exited.

remarks: @since 4.0.0

TransitionTimeout

TransitionTimeout: number | Readonly<TransitionTimeoutObject>

Either a single timeout duration in milliseconds to use for each of the TransitionActions stages, or an object of transition durations.

see: TransitionTimeout
remarks: @since 4.0.0

TransitionTimeoutObject

TransitionTimeoutObject: { [ action in keyof TransitionActions]?: number }

An object timeout values that would be used for each TransitionActions. If a value is set to 0 or undefined, the transition will not occur.

remarks: @since 4.0.0

Variables

Const CROSS_FADE_CLASSNAMES

CROSS_FADE_CLASSNAMES: Readonly<CSSTransitionClassNamesObject> = ...

The default cross fade transition classes to use.

remarks: @since 2.0.0

Const CROSS_FADE_TIMEOUT

CROSS_FADE_TIMEOUT: Readonly<TransitionTimeoutObject> = ...

The default cross fade transition timeout.

remarks: @since 2.0.0

Const DEFAULT_COLLAPSE_MIN_HEIGHT

DEFAULT_COLLAPSE_MIN_HEIGHT: 0 = 0

remarks: @since 2.0.0

Const DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM

DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM: 0 = 0

remarks: @since 2.0.0

Const DEFAULT_COLLAPSE_MIN_PADDING_TOP

DEFAULT_COLLAPSE_MIN_PADDING_TOP: 0 = 0

remarks: @since 2.0.0

Const DEFAULT_COLLAPSE_TIMEOUT

DEFAULT_COLLAPSE_TIMEOUT: Readonly<TransitionTimeoutObject> = ...

remarks: @since 2.0.0

Const SCALE_CLASSNAMES

SCALE_CLASSNAMES: Readonly<CSSTransitionClassNamesObject> = ...

The default CSSTransitionClassNames for a horizontal scale transition.

remarks: @since 2.0.0

Const SCALE_TIMEOUT

SCALE_TIMEOUT: Readonly<TransitionTimeoutObject> = ...

The default TransitionTimeout to use for horizontal and vertical scale transitions.

remarks: @since 2.0.0

Const SCALE_Y_CLASSNAMES

SCALE_Y_CLASSNAMES: Readonly<CSSTransitionClassNamesObject> = ...

The default CSSTransitionClassNames for a vertical scale transition.

remarks: @since 2.0.0

Functions

CSSTransition

CSSTransition<E>(__namedParameters: CSSTransitionProps<E>): ReactElement | null

This is a component implementation of the useCSSTransition hook that implements the temporary behavior. Since this component uses the React.cloneElement to inject the ref and className into the children, it is recommended to use the hook instead.

example

Simple Example

import { ReactElement, useState } from "react";
import { Button } from "@react-md/button":
import { CSSTransition } from "@react-md/transition";

// pretend global styles:
//
// .opacity--enter {
//   opacity: 0;
//   transition: opacity .3s;
// }
//
// .opacity--enter-active {
//   opacity: 1;
// }
//
// .opacity--exit {
//   opacity: 1;
// }
//
// .opacity--exit-active {
//   opacity: 0;
//   transition: opacity .3s;
// }

function Example(): ReactElement {
  const [transitionIn, setTransitionIn] = useState(false);

  return (
    <>
      <Button onClick={() => setTransitionIn(!transitionIn)}>
        Toggle
      </Button>
      <CSSTransition
        timeout={300}
        className="opacity"
        temporary
        transitionIn={transitionIn}
      >
        <div>
          This is some content that will animate!
        </div>
      </CSSTransition>
    </>
  );
}

remarks

@since 4.0.0

Type parameters

E: HTMLElement

An HTMLElement type used for the ref required for the transition.

Parameters

__namedParameters: CSSTransitionProps<E>

Returns ReactElement | null

Collapse

Collapse<E>(__namedParameters: CollapseProps<E>): ReactElement | null

- Defined in packages/transition/src/Collapse.tsx:68
This is a component implementation of the useCollapseTransition hook that implements the temporary behavior. Since this component uses the React.cloneElement to inject the ref and className into the children, it is recommended to use the hook instead.
example
Simple Example
```
function Example(): ReactElement {
  const [collapsed, setCollapsed] = useState(true);

  return (
    <>
      <Button onClick={() => setCollapsed(!collapsed)}>
        Toggle
      </Button>
      <Collapse collapsed={collapsed}>
        <div>
          Some content that should only be visible while not collapsed.
        </div>
      </Collapse>
    </>
  );
}
```
see
useCollapseTransition for additional examples

remarks
@since 2.0.0

remarks
@since 4.0.0 Updated for the new CSS Transition API.
Type parameters
- E: HTMLElement
  
  An HTMLElement type used for the ref required for the transition.
Parameters
- __namedParameters: CollapseProps<E>
Returns ReactElement | null

CrossFade

CrossFade<E>(__namedParameters: CrossFadeProps<E>): ReactElement | null

This is a component implementation of the useCrossFadeTransition hook that implements the temporary behavior. Since this component uses the React.cloneElement to inject the ref and className into the children, it is recommended to use the hook instead.

example

Appear transitions with a React key

import { ReactElement, useState } from "react";
import { CrossFade } from "@react-md/transition";

import Page1 from "./Page1";
import Page2 from "./Page2";
import Page3 from "./Page3";

function Example(): ReactElement {
  const [page, setPage] = useState(0):

  let content: ReactNode;
  switch (page) {
    case 0:
      content = <Page1 />
      break:
    case 1:
      content = <Page2 />
      break;
    case 2:
      content = <Page3 />
      break;
    default:
      content = null;
  }

  return (
    <>
      <Button
        onClick={() => {
          setPage(prevPage => {
            const nextPage = prevPage + 1;
            if (nextPage > 2) {
              return 0;
            }

            return nextPage;
          })
        }}
      >
        Change Page
      </Button>
      <CrossFade key={page}>
        <div>{content}</div>
      </CrossFade>
    </>
  );
}

remarks

@since 2.0.0

remarks

@since 4.0.0 Updated for the new CSS Transition API and no longer supports wrapping children in a <div>.

Type parameters

E: HTMLElement

An HTMLElement type used for the ref required for the transition.

Parameters

__namedParameters: CrossFadeProps<E>

Returns ReactElement | null

ScaleTransition

ScaleTransition<E>(__namedParameters: ScaleTransitionProps<E>): ReactElement

A component implementation of the useScaleTransition hook that just has some reasonable defaults and supports portalling the children. Since this component uses the React.cloneElement to inject the ref and className into the children, it is recommended to use the hook instead.

example

Dropdown Menu Example

import { ReactElement, useRef, useState } from "react";
import { Button } from "@react-md/button";
import { useFixedPositioning, useScaleTransition } from "@react-md/transition";

function Example(): ReactElement {
  const buttonRef = useRef<HTMLButtonElement>(null);
  const [transitionIn, setTransitionIn] = useState(false);
  const { style, transitionOptions } = useFixedPositioning({
    fixedTo: buttonRef,
  });

  return (
    <>
      <Button ref={buttonRef} onClick={() => setTransitionIn(!transitionIn)}>
        Toggle
      </Button>
      <ScaleTransition
        {...transitionOptions}
        vertical
        transitionIn={transitionIn}
      >
        <div style={style}>
          Some content within a menu
        </div>
      </ScaleTransition>
    </>
  );
}

remarks

@since 2.0.0

remarks

@since 4.0.0 The typeParam was added and the API was updated.

Type parameters

E: HTMLElement

The HTMLElement type used or the ref required for the transition.

Parameters

__namedParameters: ScaleTransitionProps<E>

Returns ReactElement

useCSSTransition

useCSSTransition<E>(__namedParameters: CSSTransitionHookOptions<E>): CSSTransitionHookReturnValue<E>

This hook is used to create CSS transitions for different components whenever a TransitionHookOptions.transitionIn flag is changed.

example

Simple Transition

import { ReactElement, useState } from "react";
import { Button } from "@react-md/button";
import { useCSSTransition } from "@react-md/transition";
import { Typography } from "@react-md/typography";

// Pretend styles
// .enter {
//   opacity: 0.5;
//   transition: opacity .15s;
// }
//
// .enter--active {
//   opacity: 1;
// }
//
// .exit {
//   opacity: 1;
//   transition: opacity .15s;
// }
//
// .exit--active {
//   opacity: 0.5;
// }

function Example(): ReactElement {
  const [transitionIn, setTransitionIn] = useState(false);
  const { elementProps } = useCSSTransition({
    timeout: 150,
    classNames: {
      enter: "enter",
      enterActive: "enter--active",
      exit: "exit",
      exitActive: "exit--active",
    },
    transitionIn,
  });

  return (
    <>
      <Button onClick={() => setTransitionIn(!transitionIn)}>
        Toggle
      </Button>
      <Typography {...elementProps}>
        Some Opacity Changing Text
      </Typography>
    </>
  );
}

example

Visibility Transition

import { ReactElement, useState } from "react";
import { Button } from "@react-md/button";
import { useCSSTransition } from "@react-md/transition";
import { Typography } from "@react-md/typography";

// Pretend styles
// .enter {
//   opacity: 0;
//   transition: opacity .2s;
// }
//
// .enter--active {
//   opacity: 1;
// }
//
// .exit {
//   opacity: 1;
//   transition: opacity .15s;
// }
//
// .exit--active {
//   opacity: 0;
// }

function Example(): ReactElement {
  const [transitionIn, setTransitionIn] = useState(false);
  const { elementProps, rendered } = useCSSTransition({
    timeout: {
      enter: 200,
      exit: 150,
    },
    classNames: {
      enter: "enter",
      enterActive: "enter--active",
      exit: "exit",
      exitActive: "exit--active",
    },
    transitionIn,
    temporary: true,
  });

  return (
    <>
      <Button onClick={() => setTransitionIn(!transitionIn)}>
        Toggle
      </Button>
      {rendered && (
        <Typography {...elementProps}>
          Some Opacity Changing Text
        </Typography>
      )}
    </>
  );
}

example

Mount Transition

import type { ReactElement } from "react";
import { useCSSTransition } from "@react-md/transition";

// Pretend styles
// .opacity {
//   opacity: 0;
//   transition: opacity .3s;
// }
//
// .opacity--active {
//   opacity: 1;
// }
//

function Example(): ReactElement {
  const { elementProps } = useCSSTransition({
    appear: true,
    transitionIn: true,
    timeout: 300,
    classNames: "opacity",
  })

  return <div {...elementProps}>Some Content!</div>;
}

remarks

@since 4.0.0

Type parameters

E: HTMLElement

An HTMLElement type used for the ref required for the transition.

Parameters

__namedParameters: CSSTransitionHookOptions<E>

Returns CSSTransitionHookReturnValue<E>

useCollapseTransition

useCollapseTransition<E>(__namedParameters: CollapseTransitionHookOptions<E>): CollapseTransitionHookReturnValue<E>

This hook is used to create a transition to collapse and expand an element inline with other content like an accordion by animating the max-height, padding-top, and padding-bottom CSS properties. The default behavior is to hide the element completely while collapsed, but providing the minHeight, minPaddingTop, and minPaddingBottom options can make this work like a "See More"/"Preview" type of element

example

Simple Example

import { ReactElement, useState } from "react";
import { Button } from "@react-md/button";
import { useCollapseTransition } from "@react-md/transition";
import { Typography } from "@react-md/typography";

function Example(): ReactElement {
  const [collapsed, setCollapsed] = useState(true);
  const { elementProps, rendered } =
    useCollapseTransition({
      transitionIn: !collapsed,
      // If the collapsible element should maintain state by not unmounting
      // while collapsed, uncomment this next line
      // temporary: false,
    });

  return (
    <>
      <Button onClick={() => setCollapsed(!collapsed)}>
        Toggle
      </Button>
      {rendered && (
        <div {...elementProps}>
          <Typography>Stuff that should be collapsed</Typography>
          <div>Whatever content...</div>
        </div>
      )}
    </>
  );
}

example

See More Example

import { ReactElement, useState } from "react";
import { Button } from "@react-md/button";
import { IconRotator } from "@react-md/icon";
import { KeyboardArrowDownSVGIcon } from "@react-md/material-icons";
import { useCollapseTransition } from "@react-md/transition";
import { Typography } from "@react-md/typography";

import styles from "./Example.module.scss";
// pretend styles:
//
// .container {
//   padding: 1rem;
//   position: relative;
// }
//
// .button {
//   position: absolute;
//   right: 0;
//   top: 0;
// }


function Example(): ReactElement {
  const [collapsed, setCollapsed] = useState(true);
  const { elementProps } =
    useCollapseTransition({
      transitionIn: !collapsed,
      minHeight: 120,
      minPaddingTop: 16,
      className: styles.container,
    });

  return (
    <div {...elementProps}>
      <Button
        aria-expanded={!collapsed}
        aria-label="Expand"
        onClick={() => setCollapsed(!collapsed)}
        buttonType="icon"
        className={styles.button}
      >
        <IconRotator rotated={!collapsed}>
          <KeyboardArrowDownSVGIcon />
        </IconRotator>
      </Button>
      <SomeComponentWithALotOfContent />
    </div>
  );
}

remarks

@since 4.0.0

Type parameters

E: HTMLElement

An HTMLElement type used for the ref required for the transition.

Parameters

__namedParameters: CollapseTransitionHookOptions<E>

Returns CollapseTransitionHookReturnValue<E>

useCrossFadeTransition

useCrossFadeTransition<E>(__namedParameters?: CrossFadeTransitionHookOptions<E>): CSSTransitionHookReturnValue<E>

This hook is used to create a "cross fade" transition -- a transition that gradually increases the opacity and transforms the element vertically a short distance. This is generally used for full page transitions when a route changes.

example

New Page Transition with @react-md/layout

import { ReactElement, ReactNode, useLayoutEffect } from "react";
import { useLocation } from "react-router-dom":
import { Layout, useLayoutNavigation } from "@react-md/layout";
import { useCrossFadeTransition } from "@react-md/transition";

import { navItems } from "./navItems";

interface ExampleProps {
  children: ReactNode;
}

function Example({ children }: ExampleProps): ReactElement {
  const { pathname } = useLocation();
  const { elementProps, transitionTo } = useCrossFadeTransition();

  const prevPathname = useRef(pathname);
  useLayoutEffect(() => {
    if (prevPathname.current === pathname) {
      return
    }

    prevPathname.current = pathname;
    transitionTo('enter');
  }, [pathname, transitionTo])

  return (
    <Layout
      {...useLayoutNavigation(navItems, pathname)}
      appBarTitle="My App"
      mainProps={elementProps}
    >
      {children}
    </Layout>
  );
}

remarks

@since 4.0.0

Type parameters

E: HTMLElement

An HTMLElement type used for the ref required for the transition.

Parameters

__namedParameters: CrossFadeTransitionHookOptions<E> = {}

Returns CSSTransitionHookReturnValue<E>

useFixedPositioning

useFixedPositioning<FixedToElement, FixedElement>(__namedParameters: FixedPositioningOptions<FixedToElement, FixedElement>): FixedPositioningHookReturnValue<FixedElement>

This hook is used to attach a temporary (fixed) element to another element within the page. In other words, this is a way to have an element with position: fixed as if it were position: absolute to a parent element that had position: relative.

example

Simple Example

import { ReactElement, useRef, useState } from "react";
import { Button } from "@react-md/button";
import { useCSSTransition, useFixedPositioning } from "@react-md/transition";

function Example(): ReactElement {
  const fixedTo = useRef<HTMLButtonElement>(null);
  const [transitionIn, setTransitionIn] = useState(false);
  const { style, transitionOptions } = useFixedPositioning({
    fixedTo,
  });
  const { elementProps, rendered } = useCSSTransition({
    ...transitionOptions,
    transitionIn,
    temporary: true,
    timeout: {
      enter: 200,
      exit: 150,
    },
    classNames: {
      enter: "enter",
      enterActive: "enter--active",
      exit: "exit",
      exitActive: "exit--active",
    },
  });

  return (
    <>
      <Button
        ref={fixedTo}
        onClick={() => setTransitionIn(!transitionIn)}
      >
        Toggle
      </Button>
      {rendered && (
        <div {...elementProps} style={style}>
          Fixed Temporary Element
        </div>
      )}
    </>
  );
}

remarks

@since 4.0.0

Type parameters

FixedToElement: HTMLElement

An HTMLElement type for the static element.
FixedElement: HTMLElement

An HTMLElement type for the fixed element.

Parameters

__namedParameters: FixedPositioningOptions<FixedToElement, FixedElement>

Returns FixedPositioningHookReturnValue<FixedElement>

useScaleTransition

useScaleTransition<E>(__namedParameters: ScaleTransitionHookOptions<E>): CSSTransitionHookReturnValue<E>

Implements a scale transition that should generally be used for temporary elements that are positioned via position: absolute or position: fixed.

example

Dropdown Menu Example

import { ReactElement, useRef, useState } from "react";
import { Button } from "@react-md/button";
import { useFixedPositioning, useScaleTransition } from "@react-md/transition";

function Example(): ReactElement {
  const buttonRef = useRef<HTMLButtonElement>(null);
  const [transitionIn, setTransitionIn] = useState(false);
  const { style, transitionOptions } = useFixedPositioning({
    fixedTo: buttonRef,
  });
  const { elementProps, rendered } = useScaleTransition({
    ...transitionOptions,
    transitionIn,
    vertical: true,
  });

  return (
    <>
      <Button ref={buttonRef} onClick={() => setTransitionIn(!transitionIn)}>
        Toggle
      </Button>
      {rendered && (
        <div {...elementProps} style={style}>
          Some content within a menu
        </div>
      )}
    </>
  );
}

remarks

@since 4.0.0

Type parameters

E: HTMLElement

The HTMLElement type used or the ref required for the transition.

Parameters

__namedParameters: ScaleTransitionHookOptions<E>

Returns CSSTransitionHookReturnValue<E>

useTransition

useTransition<E>(__namedParameters: TransitionHookOptions<E>): TransitionHookReturnValue<E>

- Defined in packages/transition/src/useTransition.ts:27
You'll most likely want to use the useCSSTransition hook instead since this is just a low-level hook that can be used to transition using timeouts.

remarks
@since 4.0.0

Type parameters
- E: HTMLElement
  
  The HTMLElement type used or the ref required for the transition.
Parameters
- __namedParameters: TransitionHookOptions<E>
Returns TransitionHookReturnValue<E>

Index

Interfaces

Type aliases

Variables

Functions

Type aliases

CSSTransitionClassNames

FixedPositioningTransitionCallbacks

TransitionEnterHandler

Type declaration

Parameters

appearing: boolean

Returns void

TransitionExitHandler

Type declaration

Returns void

TransitionScrollCallback

Type parameters

FixedToElement: HTMLElement

FixedElement: HTMLElement

Type declaration

Parameters

event: Event

data: Readonly<FixedPositioningScrollData<FixedToElement, FixedElement>>

Returns void

TransitionStage

TransitionTimeout

TransitionTimeoutObject

Variables

Const CROSS_FADE_CLASSNAMES

Const CROSS_FADE_TIMEOUT

Const DEFAULT_COLLAPSE_MIN_HEIGHT

Const DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM

Const DEFAULT_COLLAPSE_MIN_PADDING_TOP

Const DEFAULT_COLLAPSE_TIMEOUT

Const SCALE_CLASSNAMES

Const SCALE_TIMEOUT

Const SCALE_Y_CLASSNAMES

Functions

CSSTransition

Type parameters

E: HTMLElement

Parameters

__namedParameters: CSSTransitionProps<E>

Returns ReactElement | null

Collapse

Type parameters

E: HTMLElement

Parameters

__namedParameters: CollapseProps<E>

Returns ReactElement | null

CrossFade

Type parameters

E: HTMLElement

Parameters

__namedParameters: CrossFadeProps<E>

Returns ReactElement | null

ScaleTransition

Type parameters

E: HTMLElement

Parameters

__namedParameters: ScaleTransitionProps<E>

Returns ReactElement

useCSSTransition

Type parameters

E: HTMLElement

Parameters

__namedParameters: CSSTransitionHookOptions<E>

Returns CSSTransitionHookReturnValue<E>

useCollapseTransition

Type parameters

E: HTMLElement

Parameters

__namedParameters: CollapseTransitionHookOptions<E>

Returns CollapseTransitionHookReturnValue<E>

useCrossFadeTransition

Type parameters

E: HTMLElement

Parameters

__namedParameters: CrossFadeTransitionHookOptions<E> = {}