React hyper modal

Fully customizable and accessible modal react component

Welcome to the react hyper modal repository 😄 I want to introduce you to an awesome react component for displaying modal windows

Live demo

Check also the new stackable content feature!

Table of contents

• Installation
• Usage
• Properties
  • Default properties
  • Types
• Contributing
• License

Installation

You can use or package managers

$ npm i --save react-hyper-modal

or

$ yarn add react-hyper-modal

Usage

Controlled modal component

import React from 'react';
import HyperModal from 'react-hyper-modal';

...

class MyComponent extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      isModalOpen: false,
    };
  }

  ...

  openModal => this.setState({ isModalOpen: true });
  closeModal => this.setState({ isModalOpen: false });

  ...

  render() {
    const { isModalOpen } = this.state;
    return (
      <HyperModal
        isOpen={isModalOpen}
        requestClose={this.closeModal}
      >
        Your awesome modal content
      </HyperModal>
    );
  }
}

Uncontrolled modal component

import React from 'react';
import HyperModal from 'react-hyper-modal';

...

const MyComponent = () => {
  return (
    <HyperModal
      renderOpenButton={(requestOpen) => {
        return (
          <button onClick={requestOpen}>Open uncontrolled modal</button>
        );
      }
    />
  );
}

Stackable content example

To use stackable content you should use ModalStack component and children as function. Every child of ModalStack will represent a different layout.

import React from 'react';
import HyperModal, { ModalStack, ModalStackProps } from 'react-hyper-modal';

...

const Component = () => {
  const [index, setIndex] = React.useState(0)
  return (
    <HyperModal
      stackable
      stackableIndex={index}
      renderOpenButton={requestOpen => (
        <button type="button" className={styles.button} onClick={requestOpen}>Open stackable modal</button>
      )}
    >
      {(props: ModalStackProps) => (
        <ModalStack {...props}> // !!! It's very important to provide props to ModalStack
          <div style={{ color: 'red' }}>
            <div>1</div>
            <button onClick={() => setIndex(1)}>open nested</button>
            <button onClick={() => props.handleClose()}>close</button>
          </div>
          <div>
            <div>2</div>
            <button onClick={() => setIndex(2)}>open nested</button>
            <button onClick={() => setIndex(0)}>close nested</button>
            <button>close</button>
          </div>
          <div>
            <div>3</div>
            <button onClick={() => setIndex(1)}>close nested</button>
            <button onClick={() => props.handleClose()}>close</button>
          </div>
        </ModalStack>
      )}
    </HyperModal>
  )
}

That's it! 🍰✨

Properties

You can find props types and default props below the table.

* - required for controlled modal component

Default properties

{
  ariaEnabled: true,
  ariaProps: {
    'aria-describedby': 'hyper-modal-description',
    'aria-labelledby': 'hyper-modal-title',
    role: 'dialog',
  },
  disableScroll: true,
  childrenMode: true,
  closeDebounceTimeout: 0,
  closeIconPosition: {
    vertical: 'top' as const,
    horizontal: 'right' as const,
  },
  closeOnCloseIconClick: true,
  closeOnDimmerClick: true,
  closeOnEscClick: true,
  dimmerEnabled: true,
  isFullscreen: false,
  portalMode: false,
  position: {
    alignItems: 'center' as const,
    justifyContent: 'center' as const,
  },
  stackable: false,
  stackableIndex: 0,
  stackContentSettings: {
    widthRatio: 4,
    topOffsetRatio: 2,
    transition: 'all 0.3s ease',
    opacityRatio: 0.2,
  }
}

Types

type TModalPosition = 'flex-start' | 'center' | 'flex-end';
type THorizontalPosition = 'left' | 'center' | 'right';
type TVerticalPosition = 'top' | 'middle' | 'bottom';

interface IClassNamesProps {
  closeIconClassName?: string;
  contentClassName?: string;
  dimmerClassName?: string;
  portalWrapperClassName?: string;
  wrapperClassName?: string;
}

interface IARIAProps {
  'aria-describedby'?: string;
  'aria-labelledby'?: string;
  role?: string;
}

interface IPositionProps {
  alignItems?: TModalPosition;
  justifyContent?: TModalPosition;
}

interface ICloseIconPosition {
  horizontal?: THorizontalPosition;
  vertical?: TVerticalPosition;
}

interface IModalProps {
  afterClose?: () => void;
  ariaEnabled?: boolean;
  ariaProps?: IARIAProps;
  beforeClose?: () => void;
  childrenMode?: boolean;
  classes?: IClassNamesProps;
  closeDebounceTimeout?: number;
  closeIconPosition?: ICloseIconPosition;
  closeOnCloseIconClick?: boolean;
  closeOnDimmerClick?: boolean;
  closeOnEscClick?: boolean;
  dimmerEnabled?: boolean;
  isFullscreen?: boolean;
  isOpen: boolean;
  modalContentRef?: React.RefObject<HTMLDivElement>;
  modalWrapperRef?: React.RefObject<HTMLDivElement>;
  portalMode?: boolean;
  portalNode?: HTMLElement;
  position?: IPositionProps;
  renderCloseIcon?: () => JSX.Element | null | string;
  renderContent?: () => JSX.Element | JSX.Element[] | null | string;
  renderOpenButton?: boolean | ((requestOpen: () => void) => JSX.Element | string);
  requestClose: () => void;
  unmountOnClose?: boolean;
}

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT