Choosing the right surface

In the course of creating a Slack app, you will be faced with decisions on how to represent content and interaction. Depending on what type of interaction it is or piece of information you're showing your user, the surface will change. Use this guide to decide which surface is best.

This guide is broken into two parts:

• First, we explore how to decide which surface is right for the type of content you're looking to display.
• Second, we'll explore within that content, how to choose between Block Kit or Work Objects and when that is needed.

Hosting your content: choosing surfaces

Slack apps can display content in multiple surfaces; these are distinct UI containers where users may interact with your app. Each surface serves a different purpose and offers unique capabilities. Choosing the right surface depends on the user's context, the type of interaction you need, and how the content fits into their workflow.

When choosing a surface (or more than one surface), consider where the user is when they need this information and what they are trying to do.

Decision guide

Question	Surface
Is this a quick update or notification?	Messages
Does the user need a personal workspace for your app?	App Home
Are you collecting input or showing a focused task?	Modals
Is this a living document that evolves over time?	Canvases
Does the user need to manage structured records?	Lists
Should this appear alongside a message for context?	Split view pane

App Home

The App Home is a dedicated space for your app. It's private to each user and always accessible via the Apps section in Slack. Built with Block Kit, it supports interactive elements. The App Home is stateful and can show personalized, evolving content.

The App Home is best used for:

• Persistent personal workspace: Users can return to the App Home to pick up where they left off.
• Dashboards: Show users a customized view of their tasks, metrics, or activity related to your app.
• Onboarding: Guide new users through setup.
• Settings: Let users configure app preferences.
• Browsing: Present lists of items (projects, files, reports) that users can explore at their own pace.

Canvases

Canvases are rich documents that live in Slack. They support long-form content, markdown, embedded objects, and real-time collaboration. Canvases are shareable and support real-time collaborative editing. Users can draft canvases using markdown, tables, layouts, callouts, and embedded objects. Canvases are searchable and indexed.

Canvases are best used for:

• Living documents: Content that evolves over time, such as meeting notes, project plans, knowledge bases.
• Rich formatting needs: Use headings, lists, tables, images, callouts, and layouts for structured content.
• Collaborative editing: Multiple users can view and edit the same canvas simultaneously.
• Embedded context: Drop in links to messages, user profile cards, and other rich objects.

Lists

Lists are structured, table-like views with rows (items) and columns (fields) for managing collections of records. Canvases use typed fields, like text, number, date, user channel, select, checkbox, etc. They offer multiple views (grid, kanban board, timeline), and you can share and embed them in canvases. Think of them as lightweight databases inside Slack.

Lists are best used for:

• Managing records: Track tasks, bugs, requests, inventory, etc.; anything with consistent properties.
• Structured data: Each item has typed fields (text, dates, people, status, etc.).
• Filtering and sorting: Users can create custom views to organize and prioritize items.
• Collaboration: Teams can add, update, and comment on items together.

Messages

Messages are the foundation of Slack. They appear in channels, DMs, and threads where conversations happen. They can include text, Block Kit blocks, images, files, and Work Object unfurls. They support threads, reactions, and bookmarking. Messages are chronological and part of conversation history.

Messages are best used for:

• Notifications and alerts: Send timely updates that users need to see where they're already working.
• Conversational interactions: Messages fit naturally into the flow of conversation; they can be replied to, reacted to, and threaded.
• Sharing links and records: Work Object links unfurl in messages, giving rich previews of external entities.
• Quick actions: Use Block Kit buttons to let users take immediate action without leaving their conversation.

Modals

Modals are focused overlays that appear on top of Slack. They're designed for capturing input or presenting a task that requires the user's full attention. They can be multi-step and built using Block Kit. Modals are also dismissible, so a user can close it without submitting input.

Modals are best used for:

• Forms and input: Collect structured data from users (creating a task, filing a report, submitting feedback).
• Focused workflows: Guide users through a multi-step process without distractions.
• Confirmations and warnings: Ask users to confirm a destructive action or acknowledge important information.
• Detail views: Show in-depth information about a record or item that doesn't fit inline in a message.

Split view pane

The split view pane is a sidebar that appears next to a message or conversation. It provides additional context or actions without navigating away. In agents, that surface is where the user interacts with the app alongside their work. The split view pane is triggered by user interaction, like clicking on a Work Object or starting an agent interaction. It can be built using Block Kit elements, and, like modals, is also dismissible.

The split view pane is best used for:

• Contextual details: Show metadata, history, or related information about a Work Object or message.
• Quick actions: Let users take actions (approve, edit, comment) without opening a new window.
• Related content: Display threads, files, or records connected to the current conversation.
• Agent interactions: Using this surface allows users to interact with an agent alongside their work in Slack.

Side-by-side comparison

Surface	Best for	Visibility	Persistence	Interactivity	Collaboration	Searchable
App Home	Personal workspace	Private to user	Stateful	Buttons, menus	None (private)	No
Canvases	Living documents	Shareable	Long-lived	Embedded objects	Real-time editing	Yes
Lists	Structured records	Shareable	Long-lived	Table edits	Real-time editing	Yes
Messages	Notifications, conversation	Shared in channel/DM	Chronological	Buttons, menus	Threaded replies	Yes
Modals	Forms, focused tasks	Overlay (blocking)	Temporary	Form inputs	None (private)	No
Split view pane	Contextual details	Alongside message	Temporary	Buttons, menus	None (private)	No

Common mistakes to avoid

Avoid making these mistakes when choosing the appropriate surface:

• Don't use messages for complex forms. Messages aren't designed for multi-field input. Use modals instead.
• Don't use modals for passive content. If users just need to read something, use a canvas or the split view pane. Modals block the rest of the UI.
• Don't use the App Home for shared team content. The App Home is private to each user. Use canvases or lists for collaborative work.
• Don't use lists for unstructured content. If your data doesn't fit into rows and columns, use a canvas instead.
• Don't overload the split view pane. Keep it focused on contextual actions. Complex workflows belong in modals or the App Home.

Combining surfaces

The most powerful Slack apps use multiple surfaces together:

• Messages + modals: Send a notification with a button that opens a modal to collect input.
• Messages + split view pane: Share a Work Object link that opens detailed metadata in the pane.
• App Home + canvases: Show a dashboard with links to team canvases for deeper collaboration.
• Lists + messages: Send updates when list items are created or changed.
• Canvases + lists: Embed a list view in a canvas for a unified project dashboard.

Think of surfaces as complementary. Choose the right one for each interaction in your user's journey.

---

Representing your data: Block Kit vs. Work Objects

Not all content in Slack needs to be inside of a Block Kit block or Work Object. For conversational messages and simple notifications, plain text or markdown will suffice. For presenting structured data, we recommend using Block Kit and Work Objects.

Both render rich, interactive content in Slack, but they serve different purposes. Choosing the right one can boost interoperability, help the user experience, and avoid creating unnecessary engineering overhead. The determining factor is if your content represents a persistent record or an entity that lives in an external system.

Work Objects

Work Objects represent a shift from messages to entities. They are virtual records, like a Jira ticket or a Salesforce account, that have a persistent identity inside Slack. Work Objects are schema-driven, meaning you send data and Slack handles rendering. They are permanent, object-specific deep links. Work Objects are available in channels, DMs, notifications, canvases, Salesforce Lightning Experience (LEX) client, and mobile.

Work Objects are best used when the content:

• Maps to a system of record: Work Objects are the best choice for things people do work around, for example, Asana tasks, Box files, Salesforce records, Tableau metrics, emails, events, etc.
• Needs to be shareable: Unlike a Block Kit message, a Work Object has a long-lived link. Pasting that link in any channel reconstructs a consistent, rich preview using Slack's metadata schema.
• Should be a source of truth: If users need to refer back to the data over days or weeks, Work Objects are the right fit.
• Benefits from deep interoperability: Work Objects surface in Enterprise Search, show everywhere they've been shared in Slack, and support the split view pane.

Don't use Work Objects for ephemeral notifications. If the content is a one-time alert with no persistent identity, the overhead of registering a Work Object adds complexity without value.

Block Kit

Block Kit is the Slack UI framework for building custom, interactive messages. It's composed of discrete blocks (sections, images, input fields, buttons) that developers assemble into a surface. Block Kit elements are message-based and tied to a timestamp; as such, they are only shareable as part of the message they belong to. Block Kit offers a high level of customization and is available in channels, DMs, notifications, and the App Home.

Consider using Block Kit when the content:

• Can't be tied back to a system of record: If there's no persistent external entity to represent, Block Kit is the right tool.
• Is a point-in-time update: Block Kit is ideal for notifications and alerts (e.g., "A new ticket was assigned to you") that don't need a long-lived identity.
• Requires custom interactivity: Block actions and input elements give developers fine-grained control over user interactions.
• Needs full layout control: Block Kit offers the highest degree of customization among Slack's native UI options.

Don't use Block Kit to represent an external system's record. The record loses shareability, deep linking, and the native rendering improvements from Slack.

Side-by-side comparison

Format	Best for	Identity	Shareability	Customization	Interactivity	Search and discoverability	Streaming support
Work Objects	Persistent records and entities	Permanent deep link	High; link unfurls anywhere	Medium; schema-driven	Flexpane actions	Enterprise search indexed	Supported, with markdown and unfurls
Block Kit	Notifications and custom UI	Tied to message timestamp	Limited to original message	High; full layout control	Block actions, modals, inputs	Not indexed	Not supported