# redux-saga-modal

> A wrapper to manage modals within redux-saga

Latest version **1.3.2** (published 2023-05-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install redux-saga-modal
pnpm add redux-saga-modal
yarn add redux-saga-modal
bun add redux-saga-modal
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.2 |
| Published | 2023-05-23 |
| First published | 2018-08-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 67.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Karim Aziev |
| Maintainers | elgreko |
| Keywords | redux-saga, modal, redux, dialog |

## Links

- npm: https://www.npmjs.com/package/redux-saga-modal
- Repository: https://github.com/KarimAziev/redux-saga-modal
- Homepage: https://github.com/KarimAziev/redux-saga-modal#readme
- Issues: https://github.com/KarimAziev/redux-saga-modal/issues
- npm.io page: https://npm.io/package/redux-saga-modal

## Dependencies (1)

- [hoist-non-react-statics](https://npm.io/package/hoist-non-react-statics.md) ^3.3.2

## Alternatives

- [react-native-root-siblings](https://npm.io/package/react-native-root-siblings.md) — 102.9K weekly downloads
- [post-robot](https://npm.io/package/post-robot.md) — 93.7K weekly downloads
- [@praxisui/dialog](https://npm.io/package/@praxisui/dialog.md) — 2.0K weekly downloads
- [easy-toggle-state](https://npm.io/package/easy-toggle-state.md) — 350 weekly downloads
- [ngx-lightbox-evp](https://npm.io/package/ngx-lightbox-evp.md) — 19 weekly downloads

## Recent versions

- 1.3.2 (latest) — 2023-05-23
- 1.0.0-beta.12 (beta) — 2021-12-27
- 0.3.0-alpha.0 (alpha) — 2018-11-29
- 1.3.1 — 2022-08-06
- 1.3.0 — 2022-06-17
- 1.2.0 — 2022-06-15
- 1.1.1 — 2022-06-15
- 1.1.0 — 2022-05-22
- 1.0.2 — 2021-12-27
- 1.0.1 — 2021-12-27
- 1.0.0 — 2021-12-27
- 1.0.0-beta.11 — 2021-06-26
- 10.0.0-beta.10 — 2021-06-05
- 1.0.0-beta.9 — 2021-05-28
- 1.0.0-beta.8 — 2021-05-28
- … 38 more at https://npm.io/package/redux-saga-modal/versions

## README

# redux-saga-modal

Manage modals with `redux-saga`.

[![](https://img.shields.io/npm/v/redux-saga-modal.svg)](https://www.npmjs.com/package/redux-saga-modal)
[![](https://img.shields.io/codecov/c/github/KarimAziev/redux-saga-modal.svg)](https://codecov.io/gh/KarimAziev/redux-saga-modal)
[![](https://img.shields.io/npm/dt/redux-saga-modal.svg)](https://www.npmjs.com/package/redux-saga-modal)

## [Live Demo](https://codesandbox.io/s/github/KarimAziev/redux-saga-modal-example/tree/master/)

## Install

```bash
npm i redux-saga-modal
```

Or

```bash
yarn add redux-saga-modal
```

## Usage

Pass the `reducer` to your store. It keeps the state of all your modal
components, so you only have to pass it once.

```typescript
import { createStore, combineReducers } from 'redux';
import { reducer as modalReducer } from 'redux-saga-modal';

const rootReducer = combineReducers({
  // ...your other reducers
  // modalReducer should be mounted under 'modals' key,
  modals: modalReducer,
});

const store = createStore(rootReducer);
```

Connect a component to Redux Store with `sagaModal`.

```typescript
import {
  sagaModal,
  createModal,
  SagaModalInjectedProps,
} from 'redux-saga-modal';
import ReactModal from 'react-modal';
import { ReactNode } from 'react';

ReactModal.setAppElement('#root');

export interface ConfirmModalOwnProps {
  title: ReactNode;
  text: ReactNode;
}

const Confirm: React.FC<ConfirmModalOwnProps & SagaModalInjectedProps> = ({
  isOpen,
  submit,
  hide,
  title,
  text,
}) => {
  const handleSubmit = () => {
    submit();
  };
  return (
    <ReactModal isOpen={isOpen} onRequestClose={hide} closeTimeoutMS={500}>
      <h3>{title}</h3>
      <p>{text}</p>
      <div>
        <button onClick={hide}>Cancel</button>
        <button onClick={handleSubmit}>Confirm</button>
      </div>
    </ReactModal>
  );
};

const modal = createModal('confirm');

const ConnectedConfirmModal = sagaModal({
  name: modal.name,
})(Confirm);

export { modal, ConnectedConfirmModal };
```

To create an instance use `createModal` and pass the modal name as the
first argument.

```typescript
import { createModal } from 'redux-saga-modal';
const modal = createModal('CONFIRM');
```

Result

```typescript
{
  name: 'CONFIRM',
  selector: function (r) {},
  patterns: {
    show: function (n) {},
    hide: function (n) {},
    destroy: function (n) {},
    update: function (n) {},
    click: function (n) {},
    submit: function (n) {},
  },
  actions: {
    show: function (n) {},
    update: function (n) {},
    submit: function (n) {},
    click: function (n) {},
    hide: function () {},
    destroy: function () {},
  },
  takeShow: function (t) {},
  takeUpdate: function (t) {},
  takeClick: function (t) {},
  takeDestroy: function (t) {},
  takeSubmit: function (t) {},
  takeHide: function (t) {},
  show: function (r) {},
  update: function (r) {},
  click: function (r) {},
  submit: function (r) {},
  hide: function () {},
  destroy: function () {},
  select: function () {},
};
```

All methods already bound to the modal's name so you don't need manually
pass it. The instance will receive properties [actions](#actions),
[patterns](#patterns), `name`, `selector` and high-level
[effects](#effects) `show`, `update`, `hide`, `submit`, `click`,
`destroy`, `takeShow`, `takeUpdate`, `takeHide`, `takeSubmit`,
`takeClick` and `takeDestroy`.

Both `patterns` and `actions` have methods named `show`, `update`,
`hide`, `submit`, `click` and `destroy`.

```typescript
import { race } from 'redux-saga/effects';
import { createModal } from 'redux-saga-modal';

const modal = createModal('confirm');

const confirmModal = function* (initProps: ConfirmModalOwnProps) {
  yield modal.show(initProps);

  const [submit]: boolean[] = yield race([
    modal.takeSubmit(),
    modal.takeHide(),
  ]);

  yield modal.hide();

  return !!submit;
};
```

Alternatively if you don't need high-level effects you can use
[createModalHelpers](#createModalHelpers). The example above can be
rewritten like this:

```typescript
import { race, put, take } from 'redux-saga/effects';
import { createModalHelpers } from 'redux-saga-modal';
import { ConfirmModalOwnProps } from './Modal';

const modal = createModalHelpers('confirm');
const confirmModal = function* (initProps: ConfirmModalOwnProps) {
  yield put(modal.actions.show(initProps));

  const [submit]: boolean[] = yield race([
    take(modal.patterns.submit()),
    take(modal.patterns.hide()),
  ]);

  yield put(modal.actions.hide());

  return !!submit;
};
```

For frequently repeated modals tasks create a config object with modals
names as keys and tasks as values. Pass the config as the argument to
`sagas` and fork it in your rootSaga.

Your tasks will be called with a `this` context every time when an
action `showModal` has been dispatched with it's name and **cancelled**
on destroyModal.

The context of your task will have properties `actions`, `patterns`,
`name`, `selector` and high-level [effects](#effects) `show`, `update`,
`hide`, `submit`, `click`, `destroy`, `takeShow`, `takeUpdate`,
`takeHide`, `takeSubmit`, `takeClick` and `takeDestroy`.

Both `patterns` and `actions` have methods named `show`, `update`,
`hide`, `submit`, `click` and `destroy`.

```typescript
import { race, call, fork, all } from 'redux-saga/effects';
import {
  sagas as modalsSaga,
  SagaModalInstance,
  SagaModalAction,
} from 'redux-saga-modal';

interface CommentData {
  id: number;
  comment: string;
}

const saveComment = (data: CommentData) =>
  new Promise((resolve) => setTimeout(() => resolve({ ok: true }), 1000));

const saveCommentWorker = function* (this: SagaModalInstance) {
  const [submitAction]: SagaModalAction<CommentData>[] = yield race([
    this.takeSubmit(),
    this.takeHide(),
  ]);

  if (submitAction) {
    yield this.update({
      title: 'Saving',
      loading: true,
    });

    yield call(saveComment, submitAction.payload as CommentData);
    yield this.update({
      title: 'Changes saved',
      loading: false,
    });
  }

  yield this.hide();
};

const modalsTasks = {
  saveComment: saveCommentWorker,
};

export default function* rootSaga() {
  yield all([fork(modalsSaga, modalsTasks)]);
}
```

## API

- [Actions Creators](#Actions-Creators)
- [Instance Creators](#Instance-properties)
  - [createModal](#createModal)
  - [createModalHelpers](#createModalHelpers)
- [Instance properties](#Instance-properties)

  - [name](#name)
  - [actions](#actions)
  - [patterns](#patterns)
  - [selector](#selector)
  - [show](#show)
  - [update](#effects)
  - [submit](#effects)
  - [click](#effects)
  - [hide](#effects)
  - [destroy](#effects)
  - [takeShow](#effects)
  - [takeUpdate](#effects)
  - [takeSubmit](#effects)
  - [takeClick](#effects)
  - [takeHide](#effects)
  - [takeDestroy](#effects)

- [sagas](#sagas)

- [sagaModal](#sagaModal)

- [reducer](#reducer)

- [createModalActions](#createModalActions)

- [createModalEffects](#createModalEffects)

## Actions Creators

Basic actions creators.

| Name         | Arguments                            | Description                                                  |
| ------------ | ------------------------------------ | ------------------------------------------------------------ |
| showModal    | (name: String, payload: Object = {}) | Triggers to show a modal and sets payload as props           |
| updateModal  | (name: String, payload: Object = {}) | Updates the modal by merging payload with it's current props |
| submitModal  | (name: String, payload: any)         | Triggers that a target's button was pressed                  |
| clickModal   | (name: String, payload: any)         | A trigger for handling any click on modal                    |
| hideModal    | (name: String)                       | Hide modal without destroying its state in the redux store   |
| destroyModal | (name: String)                       | Close a modal by destroying its props                        |

## Instance Creators

### createModal

Creates a modal instance with properties `name`, `selector`, `actions`,
`patterns`, and [effects creators](#effects) `show`, `update`, `hide`,
`submit`, `click`, `destroy`, `takeShow`, `takeUpdate`, `takeHide`,
`takeSubmit`, `takeClick` and `takeDestroy`.

Both `patterns` and `actions` includes methods named `show`, `update`,
`hide`, `submit`, `click` and `destroy`. All methods refer to the
modal's name so you don't need manually pass it.

**Arguments**

- name(String)(Required) the name of a modal

- config(Object)

  - **getModalsState** (Function) A selector that takes the Redux
    store and returns the slice which corresponds to where the
    redux-saga-modal `reducer` was mounted. By default, the reducer
    is mounted under the `modals` key.

<!-- end list -->

```typescript
import { createModal } from 'redux-saga-modal';

const {
  name,
  selector,
  //patterns creators used for filtering actions inside take effects
  patterns: { show, click, submit, update, hide, destroy },
  //action creators
  actions: { show, click, submit, update, hide, destroy },
  //put effects (already wrapped in redux-saga put)
  show,
  click,
  submit,
  update,
  hide,
  destroy,
  //take effects (already wrapped in redux-saga take)
  takeShow,
  takeClick,
  takeSubmit,
  takeUpdate,
  takeHide,
  takeDestroy,
} = createModal('CONFIRM');
```

## createModalHelpers

Creates a [modal instance](#Instance-properties) with properties
`actions`, `patterns`, `selector` and `name`.

Both `patterns` and `actions` have methods named `show`, `update`,
`hide`, `submit`, `click` and `destroy`.

**Arguments**

- name(String)(Required) the name of a modal

- config(Object)

  - getModalsState (Function) A selector that takes the Redux store
    and returns the slice which corresponds to where the
    redux-saga-modal `reducer` was mounted. By default, the reducer
    is mounted under the `modals` key.

<!-- end list -->

```typescript
import { createModalHelpers } from 'redux-saga-modal';

const {
  name,
  selector,
  patterns: { show, click, submit, update, hide, destroy },
  actions: { show, click, submit, update, hide, destroy },
} = createModalHelpers('CONFIRM');
```

## Instance properties

### name

The name of the modal instance which was passed to `createModal` or
`createModalHelpers`. Should be the same as passed one in `sagaModal`.

### actions

Same as [basic actions creators](#Actions-Creators) but the first
argument is already bound to the modal name.

| Name    | Arguments              | Description                                                  |
| ------- | ---------------------- | ------------------------------------------------------------ |
| show    | (payload: Object = {}) | Triggers to show a modal and sets payload as it's props      |
| update  | (payload: Object = {}) | Updates the modal by merging payload with it's current props |
| submit  | (payload: any)         | Triggers that a target's button was pressed                  |
| click   | (payload: any)         | A trigger for handling any click on modal                    |
| hide    | ()                     | Hide modal without destroying its state in the redux store   |
| destroy | ()                     | Close a modal by destroying its props                        |

**Example**

```typescript
import { createModal, createModalActions, showModal } from 'redux-saga-modal';

const modal = createModal('CONFIRM');
yield put(modal.actions.show({ title: 'Some title' }));

//or
const confirmActions = createModalActions('CONFIRM');
yield put(confirmActions.show({ title: 'Some title' }));

//or
yield put(showModal('CONFIRM', { title: 'Some title' }));
```

### patterns

Matcher methods for filtering modal actions inside `redux-saga` take
effects, such as `take`, `takeLatest`, `takeEvery` etc. Every pattern
accepts optional argument for checking payload.

Payload pattern has the
[same](https://redux-saga.js.org/docs/api/#takepattern) meaning and
rules as in the `redux-saga` but applies not for the whole action but
only to its payload.

| Name    | Arguments               | Description                                                                  |
| ------- | ----------------------- | ---------------------------------------------------------------------------- |
| show    | payloadPattern?: String | Function                                                                     |
| update  | payloadPattern?: String | Function                                                                     |
| submit  | payloadPattern?: String | Function                                                                     |
| click   | payloadPattern?: String | Function                                                                     |
| hide    |                         | An action matcher for `hideModal` with the same name as it's instance has    |
| destroy |                         | An action matcher for `destroyModal` with the same name as it's instance has |

**Example**

```typescript
import { createModal } from 'redux-saga-modal';

const { patterns } = createModal('CONFIRM');

//result: take(action => action.type === clickModal().type && action.meta.name === 'CONFIRM' && payload === 'value'
yield take(patterns.click(payload === 'value'));

//result: take(action => action.type === clickModal().type && action.meta.name === 'CONFIRM' && payload && payload.text === 'Some text'

yield take(patterns.show((payload) => payload && payload.text === 'Some text'));

//result: take(action => action.type === clickModal().type && action.meta.name === 'CONFIRM'
yield take(patterns.click);
```

### selector

```typescript
import { createModal } from 'redux-saga-modal';

const { selector, ...effects } = createModal('CONFIRM');

// the same
yield select(selector);
yield effects.select();
```

### effects

Produced with `createModal` or `createModalEffects`. Returns scoped
`put`, `select` and `take` effects.

Payload pattern in the `take` effects has the same meaning and rules as
in's the `redux-saga`, but applies not for the whole action but only to
the payload.

| Name        | Arguments                | Effect   |                                                                       |
| ----------- | ------------------------ | -------- | --------------------------------------------------------------------- |
| show        | (payload: Object)        | put      | Triggers to show a modal and sets payload as it's props               |
| update      | (payload: Object)        | put      | Updates the modal by merging payload with it's current props          |
| submit      | (payload: any)           | put      | Triggers that a target's button was pressed                           |
| click       | (payload: any)           | put      | A trigger for handling any click on modal                             |
| hide        | (name: String)           | put      | Hide modal without destroying it's state in the redux store           |
| destroy     | (name: String)           | put      | Close a modal by destroying it's props                                |
| select      | (name: String)           | select   | Select a modal state from the Redux Store                             |
| takeShow    | (payloadPattern?: String | Function | Array                                                                 |
| takeUpdate  | (payloadPattern?: String | Function | Array                                                                 |
| takeSubmit  | (payloadPattern?: String | Function | Array                                                                 |
| takeClick   | (payloadPattern?: String | Function | Array                                                                 |
| takeHide    |                          | take     | Returns a `take` effect for an action `hideModal` with scoped name    |
| takeDestroy |                          | take     | Returns a `take` effect for an action `destroyModal` with scoped name |

**Example**

```typescript
import { createModal } from 'redux-saga-modal';

const { name, ...effects } = createModal('CONFIRM');

//result: put(showModal('CONFIRM', ({ text: 'Some text' }))
yield effects.show({ text: 'Some text' });

//result: take(action => action.type === clickModal().type && action.meta.name === 'CONFIRM' && payload === 'value'
yield effects.takeClick('value');

//result: take(action => action.type === clickModal().type && action.meta.name === 'CONFIRM' && payload && payload.text === 'Some text'
yield effects.takeClick((payload) => payload && payload.text === 'Some text');
//result: take(action => action.type === clickModal().type && action.meta.name === 'CONFIRM'
yield effects.takeClick();
```

## sagas

Invoke your sagas with a `this` context whenever an action `showModal`
has been dispatched with passed name and **cancelled** on
`destroyModal`.

**Arguments**

- config(Object)(Required)

  - \<\[key: ModalName\], Saga: Generator\>

## sagaModal

Connects a component to Redux store and injects next props:

- modal: { name }
- name;
- isOpen;
- show;
- update;
- destroy;
- click;
- submit;
- hide;
- showModal;
- updateModal;
- submitModal;
- clickModal;
- hideModal;
- destroyModal;

**Arguments**

- name(String)(Required) the name of a modal

- config(Object)

  - **name** (String)(Required) the name of a modal
  - **getModalsState** (Function) A selector that takes the Redux
    store and returns the slice which corresponds to where the
    redux-saga-modal `reducer` was mounted. By default reducer is
    mounted under the 'modals' key: `state => state.modals`
  - **actions** (Object) Custom actions to bind with redux
    `dispatch`
  - **keepComponentOnHide** (Boolean) Whether keep modal component
    when `isOpen` equals `false` By default equals `false`
  - **destroyOnHide** (Boolean) Whether automatically dispatch
    `destroy` to after `hide`. By default equals `true`

## reducer

The modals reducer keeps state of the all modals. Should be mounted to
redux store under name `modals` or any other but in this case you need
to pass selector `getModalsState` to `sagaModal`, `createModal` and
`createModalHelpers`.

## createModalActions

**Arguments**

- name(String)(Required) the name of a modal

Creates [actions creators](#actions) `show`, `update`, `hide`, `submit`,
`click` and `destroy` bound to the name of the modal.

## createModalEffects

**Arguments**

- name (String)(Required) the name of a modal

Creates [effects](#effects) `show`, `update`, `hide`, `submit`, `click`
and `destroy` bound to the name of the modal.

## createModalPatterns

**Arguments**

- name(String)(Required) the name of a modal

Creates [patterns creators](#patterns) `show`, `update`, `hide`,
`submit`, `click` and `destroy` bound to the name of modal. Every
pattern accepts optional matcher for checking payload.

## License

MIT © [KarimAziev](https://github.com/KarimAziev)

---
_Source: https://npm.io/package/redux-saga-modal · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
