react-st-modal
Version:
React St Modal is a simple and flexible library for implementing modal dialogs
272 lines (224 loc) • 8.42 kB
Markdown
[](https://github.com/Nodlik/react-st-modal/blob/master/LICENSE) [](https://www.npmjs.com/package/react-st-modal) [](https://npmcharts.com/compare/react-st-modal?minimal=true) [](https://www.buymeacoffee.com/nndlik)
---
# [react-st-modal](https://nodlik.github.io/react-st-modal/)
---
React St Modal is a simple and flexible library for implementing modal dialogs.
### Features
* Simple and easy to use api
* Compatible with mobile devices
* Implemented standard interaction functions: alert, confirm, prompt
* Async/await syntax
* Customization via css variables
* Accessibility and focus control
* Dynamic call of modal dialogs, which does not require definition in code
* No third party libraries
---
**DEMO AND DOCS:** https://nodlik.github.io/react-st-modal/
---
## Getting started
### Installation
You can install the latest version using npm:
```shell
npm install react-st-modal
```
### Overview
To implement the functionality of modal dialogs this library has four functions and one react component.
Functions `Alert`, `Confirm`, `Prompt` implement the behavior of existing browser functions.
Function `CustomDialog` shows any JSX element in a modal window.
React component `StaticDialog` is used to define modals in your JSX element.
### Interaction: (`Alert`, `Prompt`, `Confirm`)
All interaction functions are async.
| Method name | Parameters | Return type | Description|
| ----------- | ---------- | ----------- | ---------- |
| `Alert` | `body`: `JSX.Element (string)`, `title?`: `string`, `buttonText?`: `string` | `void` | Shows a message (`body`) and waits for the user to press button |
| `Confirm` | `body`: `JSX.Element (string)`, `title?`: `string`, `okButtonText?`: `string`, `cancelButtonText?`: `string` | `boolean` | Shows a modal window with a text (`body`) and two buttons: OK and Cancel. The result is `true` if OK is pressed and `false` otherwise|
| `Prompt` |`title?`: `string`, `options?`: `PromptConfig` | `string` | Shows a modal window with a text message, an input field for the visitor, and the buttons OK/Cancel|
`PromptConfig` allows you to specify the following optional parameters:
* `defaultValue: string | number`
* `isRequired: boolean`
* `errorText: string`
* `okButtonText: string`
* `cancelButtonText: string`
**Example**
```jsx
import { Confirm } from 'react-st-modal';
function ConfirmExample() {
return (
<div>
<button
onClick={async () => {
const result = await Confirm('Сonfirmation text',
'Сonfirmation title');
if (result) {
// Сonfirmation confirmed
} else {
// Сonfirmation not confirmed
}
}}
>
Show confirm
</button>
</div>
);
}
```
---
### `CustomDialog`
`CustomDialog` is an async function that shows any element in a modal window.
**Parameters**
* `body: JSX.Element` - the element shown in the modal dialog
* `options?: CustomConfig` - specified options
`CustomConfig` allows you to specify the following optional parameters:
* `title?: string` - modal dialog title
* `className?: string` - css className
* `defaultBodyOverflow?: string` (default: `visible`) - default value to `body` css property `overflow`
* `showCloseIcon?: boolean` (default: `false`) - show close button in the top corner of the window
* `isCanClose?: boolean` (default: `true`) - is it possible to close the dialog by clicking on the overlay or ESC button
* `isFocusLock?: boolean` (default: `true`) - lock focus on modal
* `isBodyScrollLocked?: boolean` (default: `true`) - content scrolling lock
* `replaceScrollBar?: boolean` (default: `true`) - whether to replace the body scrollbar with a placeholder
* `scrollBarPlaceholderColor?: string` (default: `#eeeeee`) - default color for the scrollbar placeholder
* `onAfterOpen?: () => void` - event called after the dialog was opened
To control a dialog from an inner element, use `useDialog<T>` hook
`useDialog<T>` returns an object containing:
* `isOpen: boolean` - the current state of the modal
* `close: (result?: T) => void` - function that closes the dialog and returns the result
**Example**
```jsx
import { CustomDialog, useDialog } from 'react-st-modal';
// The element to be shown in the modal window
function CustomDialogContent() {
// use this hook to control the dialog
const dialog = useDialog();
const [value, setValue] = useState();
return (
<div>
<input
type="text"
onChange={(e) => {
setValue(e.target.value);
}}
/>
<button
onClick={() => {
// Сlose the dialog and return the value
dialog.close(value);
}}
>
Custom button
</button>
</div>
);
}
function CustomExample() {
return (
<div>
<button
onClick={async () => {
const result = await CustomDialog(
<CustomDialogContent />,
{
title: 'Custom Dialog',
showCloseIcon: true,
}
);
}}
>
Custom
</button>
</div>
);
}
```
---
### `StaticDialog`
`StaticDialog` it is a React component that used to define modals in your JSX element
**Props**
* `isOpen: boolean` - describing if the modal should be shown or not
* `children: React.ReactNode` - the element shown in the modal dialog
* `title?: string` - modal dialog title
* `className?: string` - css className
* `defaultBodyOverflow?: string` (default: `visible`) - default value to `body` css property `overflow`
* `showCloseIcon?: boolean` (default: `false`) - show close button in the top corner of the window
* `isCanClose?: boolean` (default: `true`) - is it possible to close the dialog by clicking on the overlay or ESC button
* `isFocusLock?: boolean` (default: `true`) - lock focus on modal
* `isBodyScrollLocked?: boolean` (default: `true`) - content scrolling lock
* `replaceScrollBar?: boolean` (default: `true`) - whether to replace the body scrollbar with a placeholder
* `scrollBarPlaceholderColor?: string` (default: `#eeeeee`) - default color for the scrollbar placeholder
* `onAfterClose?: (result?: T) => void` - event called after the dialog was closed
* `onAfterOpen?: () => void` - event called after the dialog was opened
**Example**
```jsx
import { StaticDialog, useDialog } from 'react-st-modal';
function CustomStaticExample() {
const [isOpen, setOpen] = useState(false);
return (
<div>
<StaticDialog
isOpen={isOpen}
title="Custom static dialog"
onAfterClose={(result) => {
setOpen(false);
// do something with dialog result
}}
>
{/* see previous demo */}
<CustomDialogContent />
</StaticDialog>
<div>
<button
onClick={() => {
setOpen(true);
}}
>
Custom static
</button>
<div>
</div>
);
}
```
---
### UI Elements
To decorate your dialogs, you can use the following components: `ModalButton`, `ModalContent`, `ModalFooter`
**Example**
```jsx
import { ModalContent, ModalFooter, ModalButton, useDialog } from 'react-st-modal';
function CustomDialogContent() {
const dialog = useDialog();
const [value, setValue] = useState<string>();
return (
<div>
<ModalContent>
<div>Custom dialog content</div>
<label>
Input value:
<input
type="text"
onChange={(e) => {
setValue(e.target.value);
}}
/>
</label>
</ModalContent>
<ModalFooter>
<ModalButton
onClick={() => {
dialog.close(value);
}}
>
Custom button
</ModalButton>
</ModalFooter>
</div>
);
}
```
---
### Contacts
Oleg,
<oleg.litovski9@gmail.com>
[![Buy me a coffee][buymeacoffee-shield]][buymeacoffee]
[buymeacoffee]: https://www.buymeacoffee.com/nndlik
[buymeacoffee-shield]: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png