Modals: focused spaces for user interaction

---

Modular modals

Modals are the Slack app equivalent of alert boxes, pop-ups, or dialog boxes. They capture and maintain focus within Slack until the user submits or dismisses the modal. This makes them a very powerful piece of app functionality that must be wielded carefully.

Each modal consists of some standardized UI elements — a title, an x button to dismiss the modal, a cancel button — that wrap around a fully-customizable space — the modal's view.

View this example

To generate a modal, an app will need to compose an initial view. Apps can compose view layouts and add interactivity to views by using Block Kit.

A modal can hold up to 3 views at one time in a view stack. There is only ever a single view visible at a given moment, but the view stack can retain previous views, returning to them with their prior state still in place.

An app can push new views onto a modal's view stack or update an existing view within that stack — including the currently visible view.

Let's look at this whole process in a bit more detail.

---

The lifecycle of a modal

In the beginning, there was a user interaction.

This interaction happened with one of an app's entry point features. As a result of the interaction, the app is sent a payload containing a special trigger_id.

An app composes an initial view, mixes it with the trigger_id potion, recites a magic spell, and abracadabra! — a new modal is created ✨.

This new modal has a view stack containing just that initial view. The view stack can be manipulated by apps in a few ways over the course of a modal's lifetime:

Updating views

Updating a view can happen at any time while the modal is opened. This update can change the contents and layout of the view entirely, if necessary.

A view update should usually only happen in response to the use of interactive components or inputs in the view.

Adding new views

Apps can push a new view onto the modal's view stack. This will cause that view to immediately become visible. Three views can exist in the view stack at any one time.

Again, an app pushing a new view should usually only happen in response to the use of interactive components or inputs in one of the previous views.

Closing views

When a view contains inputs, a user will be able to submit the modal when that view is visible. If that happens, the app can choose to close that specific view or all views in the view stack.

Closing a single view will remove it from the view stack, and cause the next view in the stack to appear again. Closing all views will close the modal entirely.

Modals can also be dismissed entirely by users at any point by clicking on the standard cancel or x buttons.

Chaining views together through pushes, updates, and deliberate closures can provide a very sophisticated and deep interface for your app. Workflows can be encapsulated entirely within a modal, focusing the user on completing their task, and then getting right back to their workspace.

To read greater detail on this modal lifecycle (we've got diagrams), and to learn how to manipulate a modal's view stack, complete our guide to using modals.

---

Gathering user input

In order to capture user input, a special type of Block Kit component is available called an input block.

An input block can hold a plain-text input, a select menu, or a multi-select menu. Plain-text inputs can be set to accept single or multi-line text.

See the full input block definition in the input block reference.

If you're using any input blocks, you must include the submit field when defining your view.

---

Modal shift

Now you know the basic story of a modal, it's time to try your hand at your own. Read our guide to using modals to start utilizing the magic powers contained within.

If you've used our outmoded dialogs in your apps, check out our guide to upgrading dialogs to modals.