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

Props | Description ------------ | ------------- afterClose | callback that is called after closing ariaEnabled | enable ARIA properties ariaProps | custom ARIA properties beforeClose | callback that is called before closing childrenMode | describing if the modal content should be rendered as React Children classes | overriding default modal class names closeDebounceTimeout | time to close modal closeIconPosition | position of close button closeOnCloseIconClick | close the modal by pressing close button closeOnDimmerClick | close the modal by pressing on dimmer closeOnEscClick | close the modal by pressing ESC dimmerEnabled | describing if the dimmer should be shown or not isFullscreen | describing if the modal should be shown in full screen or not isOpen * | describing if the modal should be shown or not modalContentRef | reference to the modal content div modalWrapperRef | reference to the modal wrapper div portalMode | describing if the modal should be rendered in React Portal or not portalNode | HTML node to create React Portal position | setting the modal position renderCloseIcon | callback for rendering custom close button renderContent | callback for rendering custom modal content renderOpenButton | callback or boolean describing if the modal should be uncontrolled component requestClose * | callback to close the modal stackable | make content stackable stackableIndex | stack length stackContentSettings | stackable content settings unmountOnClose | describing if the modal should be unmounted when close

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