Muokkaa

Jaa


Designing dialogs for your Microsoft Teams app

You can create modal pop-up experiences in your Teams app with dialogs (referred as task modules in TeamsJS v1.x). Use this capability to display rich media and information or complete a complex task.

Example shows a dialog.

Microsoft Teams UI Kit

You can find more comprehensive dialog design guidelines, including elements that you can grab and modify as needed, in the Microsoft Teams UI Kit.

Open a dialog

Dialogs can be launched from almost anywhere in your app.

  • Tab: A dialog can be launched from any link within a tab. Use in scenarios where you want the user to focus on an interaction.
  • Bot: A dialog can be launched from a link inside a bot message.
  • Adaptive Card: A dialog can be launched from an Adaptive Card (sent with a message extension or by a bot) when a user selects a button.
  • Message extension (action commands): Message extensions allow you to take a particular action on message content. Selecting an action opens a dialog.
  • Message extension (compose box context): In the compose box, you can design a message extension to open a dialog instead of the typical flyout. Reserve dialogs for complex interactions, such as completing a form.

Anatomy

Dialogs provide a flexible surface for hosted app experiences. They're built using an iframe (desktop) or webview (mobile), so you can design dialogs with our UI templates (recommended) or from scratch.

They can also be built with the Adaptive Cards framework, which can be a simpler and faster way to facilitate common scenarios (such as forms).

Mobile

Illustration showing the UI anatomy of a dialog on mobile.

Counter Description
1 Header: Make headers clear and concise. Describe the task you want users to complete.
2 App name: Full name of your app.
3 Close button: Closes the dialog. Does not apply unsaved changes in the app content.
4 webview: Responsive space that hosts your app content.
5 Actions (optional): Buttons related to your app content.

Desktop

Illustration showing the UI anatomy of a dialog.

Counter Description
1 App icon
2 App name: Full name of your app.
3 Header: Make headers clear and concise. Describe the task you want users to complete.
4 Close button: Closes the dialog. Does not apply unsaved changes in the app content.
5 iframe: Responsive space that hosts your app content.
6 Actions (optional): Buttons related to your app content.

Designing with UI templates

Consider using templates for common layouts inside your dialogs. Each one is made up of smaller components to create an elegant, responsive design that can be used out of the box or customized for your scenario or with your brand look and feel.

  • List: Lists can display related items in a scannable format and allow users to take actions on an entire list or individual items.
  • Form: Forms are for collecting, validating, and submitting user input in a structured way.
  • Empty state: The empty state template can be used for many scenarios, including sign in, first-run experiences, error messages, and more.

Examples

List

Lists work nicely in a dialog because they're easy to scan.

Mobile

Example list in a dialog on mobile.

Desktop

Example list in a dialog.

Form

Dialogs are a great place to surface forms with sequential user inputs and inline validation. You can leverage Adaptive Cards as a way to embed form elements.

Mobile

Example form in a dialog on mobile.

Desktop

Example form in a dialog.

Sign in

Create a focused sign in or sign up flow with a series of dialogs, letting users move easily through sequential steps.

Mobile

Example sign in experience in a dialog on mobile.

Desktop

Example sign in experience in a dialog.

Media

Embed media content in a dialog for a focused viewing experience.

Mobile

Example media content in a dialog on mobile.

Desktop

Example media content in a dialog.

Empty state

Use for welcome, error, and success messages.

Mobile

Example empty state in a dialog on mobile.

Desktop

Example empty state in a dialog.

Embed a gallery carousel in an iframe (desktop) or webview (mobile).

Mobile

Example image gallery in a dialog on mobile.

Desktop

Example image gallery in a dialog.

Poll

This example shows poll results launched from an Adaptive Card. The poll can be placed inside a dialog, too.

Mobile

Example poll in a dialog on mobile.

Desktop

Example poll in a dialog.

Best practices

Use these recommendations to create a quality app experience.

Usability

Example showing a dialog best practice (one dialog at a time).

Do: Show one dialog at a time

The goal is to focus the user on completing a task after all!

Example showing a dialog best practice (pop a dialog on top of a dialog).

Don't: Pop a dialog on top of a dialog

This creates an unfocused, confusing user experience.

Responsive

Example showing a dialog best practice (make sure the content is responsive).

Do: Make sure the content is responsive

While Adaptive Cards hosted in a dialog render well on mobile devices, if you choose to use an iframe to host app content, make sure the UI is responsive and works well across devices.

Example showing a dialog best practice (don't use horizontal scroll bars).

Don't: Use horizontal scroll bars

It's a best practice to keep content focused and not too lengthy. If a scroll is necessary, scroll vertically and not horizontally.

Simplicity

Example showing a dialog best practice (keep it short).

Do: Keep it short

You can easily create a multi-step wizard, but that doesn't necessarily mean you should! A multi-screen dialog can be problematic because incoming messages are distracting and tempt users to exit. If your task is really involved, pop out to a full webpage instead of a dialog.

Example showing a dialog best practice (don't have long interactions).

Don't: Have long interactions

Try to keep your interactions short and to the point.

Error messages

Example showing a dialog best practice (use inline error messages).

Do: Use inline error messages

See the forms UI template for guidelines on inline error handling.

Example showing a dialog best practice (put error messages in dialogs).

Don't: Put error messages in dialogs

Don't pop an error message in a dialog on top of a dialog. It creates a confusing user experience.