Skip to main content
react-md

useCollapseTransition

function useCollapseTransition<E extends HTMLElement>(
  options: CollapseTransitionHookOptions<E>
): CollapseTransitionHookReturnValue<E>;

This useCollapseTransition 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 Usage

See the Collapse demos for examples.

Parameters

export interface CollapseTransitionHookOptions<E extends HTMLElement>
  extends Omit<PreconfiguredCSSTransitionOptions<E>, "exitedHidden">,
    CollapseConfigurationStyle {
  /**
   * An optional style to merge with the required collapse transition styles.
   *
   * If any keys from the {@link CollapseStyle} are included in this object,
   * these styles will override and possibly break the collapse transition.
   */
  style?: CSSProperties;

  /**
   *
   * @see {@link DEFAULT_COLLAPSE_TIMEOUT}
   * @defaultValue `DEFAULT_COLLAPSE_TIMEOUT`
   */
  timeout?: TransitionTimeout;

  /**
   *
   * @defaultValue `minHeight === 0 && minPaddingTop === 0 && minPaddingBottom === 0`
   */
  temporary?: boolean;
}

export interface CollapseConfigurationStyle {
  /**
   * The minimum height that the collapsed element can be which defaults to `0`.
   * This can either be a number of pixels or a string CSS height value.
   *
   * Setting this value to any non-zero value will allow for the element to
   * shrink to the defined min-height, and then expand to the full height once
   * no longer collapsed.
   *
   * Note: If the `minHeight`, `minPaddingTop`, and `minPaddingBottom` options
   * are all set to `0` (default), the child will be removed from the DOM while
   * collapsed.
   *
   * @defaultValue `0`
   */
  minHeight?: number | string;

  /**
   * The minimum padding-top that the collapsed element can be which defaults to
   * `0`. This can either be a number of pixels or a string CSS `padding-top`
   * value.
   *
   * Note: If the `minHeight`, `minPaddingTop`, and `minPaddingBottom` options
   * are all set to `0` (default), the child will be removed from the DOM while
   * collapsed.
   *
   * @defaultValue `0`
   */
  minPaddingTop?: number | string;

  /**
   * The minimum padding-bottom that the collapsed element can be which defaults
   * to `0`. This can either be a number of pixels or a string CSS
   * `padding-bottom` value.
   *
   * Note: If the `minHeight`, `minPaddingTop`, and `minPaddingBottom` options
   * are all set to `0` (default), the child will be removed from the DOM while
   * collapsed.
   *
   * @defaultValue `0`
   */
  minPaddingBottom?: number | string;
}

Returns

An object with the following definition:

export interface CollapseTransitionHookReturnValue<E extends HTMLElement>
  extends CSSTransitionHookReturnValue<E>,
    CollapseElementProps<E> {
  /**
   * This is just a convenience object so that you don't need to destructure as
   * many variables to pass to an element.
   *
   * @example Simple Usage
   * ```tsx
   * const { elementProps, rendered } = useCollapseTransition({
   *   // ...options
   *   transitionIn,
   * });
   *
   * if (!rendered) {
   *   return null
   * }
   *
   * return <div {...elementProps}>{children}</div>;
   *
   * // This is the long-hand version
   * const { ref, style, className, hidden, rendered } = useCollapseTransition({
   *   // ...options
   *   transitionIn,
   * });
   *
   * if (!rendered) {
   *   return null
   * }
   *
   * return (
   *   <div
   *     ref={ref}
   *     style={style}
   *     className={className}
   *     hidden={hidden}
   *   >
   *     {children}
   *   </div>
   * );
   * ```
   */
  elementProps: Readonly<CollapseElementProps<E>>;
}

export interface CollapseElementProps<E extends HTMLElement>
  extends CSSTransitionElementProps<E> {
  /**
   * A merged styled object required for the collapse transition to work.
   *
   * @see {@link CollapseStyle}
   * @see {@link CollapseTransitionHookOptions.style}
   */
  style: CSSProperties;
}

See Also