CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-slack--types

Comprehensive TypeScript type definitions for building Slack applications and integrations with the Node Slack SDK

94

1.11x
Overview
Eval results
Files

views.mddocs/

Views and Modals

Views define the structure of Slack's interactive surfaces including modals, App Home tabs, and workflow step configurations. They provide the foundation for building rich user interfaces within Slack.

Capabilities

View Types

Union type covering all supported view types.

type View = HomeView | ModalView | WorkflowStepView;

Base View Interface

Common properties shared by all view types.

interface BaseView {
  blocks: AnyBlock[];
  private_metadata?: string;
  callback_id?: string;
  external_id?: string;
}

Modal View

Interactive modal dialogs with titles, submit/close buttons, and content blocks.

interface ModalView extends BaseView {
  type: 'modal';
  title: PlainTextElement;
  close?: PlainTextElement;
  submit?: PlainTextElement;
  clear_on_close?: boolean;
  notify_on_close?: boolean;
}

Usage Example:

import { ModalView, InputBlock, PlainTextInput } from "@slack/types";

const modal: ModalView = {
  type: "modal",
  title: {
    type: "plain_text",
    text: "User Registration"
  },
  submit: {
    type: "plain_text",
    text: "Submit"
  },
  close: {
    type: "plain_text",
    text: "Cancel"
  },
  blocks: [
    {
      type: "input",
      block_id: "name_input",
      label: {
        type: "plain_text",
        text: "Full Name"
      },
      element: {
        type: "plain_text_input",
        action_id: "name_value",
        placeholder: {
          type: "plain_text",
          text: "Enter your full name"
        }
      }
    },
    {
      type: "input",
      block_id: "email_input",
      label: {
        type: "plain_text",
        text: "Email Address"
      },
      element: {
        type: "email_text_input",
        action_id: "email_value",
        placeholder: {
          type: "plain_text",
          text: "your.email@example.com"
        }
      }
    }
  ],
  callback_id: "user_registration_modal",
  private_metadata: "registration_flow_v1"
};

Home View

App Home tab interface for displaying custom content in the user's App Home.

interface HomeView extends BaseView {
  type: 'home';
}

Usage Example:

import { HomeView, SectionBlock, HeaderBlock } from "@slack/types";

const homeView: HomeView = {
  type: "home",
  blocks: [
    {
      type: "header",
      text: {
        type: "plain_text",
        text: "Welcome to Your Dashboard"
      }
    },
    {
      type: "section",
      text: {
        type: "mrkdwn",
        text: "Here's a summary of your recent activity:"
      }
    },
    {
      type: "section",
      fields: [
        {
          type: "mrkdwn",
          text: "*Tasks Completed:*\n25"
        },
        {
          type: "mrkdwn",
          text: "*Messages Sent:*\n142"
        }
      ]
    },
    {
      type: "actions",
      elements: [
        {
          type: "button",
          text: {
            type: "plain_text",
            text: "View Reports"
          },
          action_id: "view_reports",
          style: "primary"
        },
        {
          type: "button",
          text: {
            type: "plain_text",
            text: "Settings"
          },
          action_id: "open_settings"
        }
      ]
    }
  ]
};

Workflow Step View (Deprecated)

Configuration modal for legacy Workflow Steps from Apps.

interface WorkflowStepView extends BaseView {
  type: 'workflow_step';
  submit_disabled?: boolean;
}

Note: Workflow Steps from Apps are deprecated and will no longer be executed starting September 12, 2024.

View Properties

Blocks Array

All views contain an array of blocks that define their content structure.

blocks: AnyBlock[];

The blocks array can contain any valid Block Kit blocks:

  • ActionsBlock - Interactive elements
  • ContextBlock - Contextual information
  • DividerBlock - Visual separators
  • HeaderBlock - Section headers
  • ImageBlock - Image displays
  • InputBlock - Form inputs (modals only)
  • SectionBlock - Text content with optional accessories
  • RichTextBlock - Formatted rich text
  • VideoBlock - Embedded videos

Private Metadata

String data passed to interaction payloads for maintaining state.

private_metadata?: string;

Usage Example:

const modal: ModalView = {
  // ... other properties
  private_metadata: JSON.stringify({
    user_id: "U123456",
    flow_step: "confirmation",
    original_message_ts: "1609459200.000300"
  })
};

Callback ID

Identifier for recognizing view interactions and submissions.

callback_id?: string;

External ID

Custom identifier unique per team for external reference.

external_id?: string;

Modal-Specific Properties

Title

Required title displayed in modal header.

title: PlainTextElement;

Submit Button

Optional submit button text (required when input blocks are present).

submit?: PlainTextElement;

Close Button

Optional close button text.

close?: PlainTextElement;

Clear on Close

When true, clicking close clears all modal views and closes the modal.

clear_on_close?: boolean;

Notify on Close

When true, sends view_closed event when user clicks close button.

notify_on_close?: boolean;

Modal Interaction Patterns

Modals support several interaction patterns:

Form Collection

Use input blocks to collect structured data from users:

const formModal: ModalView = {
  type: "modal",
  title: { type: "plain_text", text: "Project Details" },
  submit: { type: "plain_text", text: "Create Project" },
  blocks: [
    {
      type: "input",
      label: { type: "plain_text", text: "Project Name" },
      element: {
        type: "plain_text_input",
        action_id: "project_name"
      }
    },
    {
      type: "input",
      label: { type: "plain_text", text: "Team Members" },
      element: {
        type: "multi_users_select",
        action_id: "team_members",
        placeholder: { type: "plain_text", text: "Select team members" }
      }
    },
    {
      type: "input",
      label: { type: "plain_text", text: "Due Date" },
      element: {
        type: "datepicker",
        action_id: "due_date"
      }
    }
  ]
};

Multi-Step Workflows

Use private_metadata to track workflow state across multiple modal views:

const step1Modal: ModalView = {
  type: "modal",
  title: { type: "plain_text", text: "Setup - Step 1 of 3" },
  submit: { type: "plain_text", text: "Next" },
  blocks: [/* step 1 content */],
  private_metadata: JSON.stringify({ step: 1, data: {} }),
  callback_id: "setup_workflow"
};

Dynamic Content

Modal content can be updated using the views.update API method with the same view structure.

App Home Patterns

App Home views provide a persistent interface for users:

Dashboard Layout

const dashboardHome: HomeView = {
  type: "home",
  blocks: [
    { type: "header", text: { type: "plain_text", text: "Dashboard" } },
    { type: "divider" },
    {
      type: "section",
      text: { type: "mrkdwn", text: "*Recent Activity*" },
      accessory: {
        type: "button",
        text: { type: "plain_text", text: "Refresh" },
        action_id: "refresh_dashboard"
      }
    }
  ]
};

Navigation Menu

const navigationHome: HomeView = {
  type: "home",
  blocks: [
    {
      type: "actions",
      elements: [
        {
          type: "button",
          text: { type: "plain_text", text: "📊 Reports" },
          action_id: "show_reports"
        },
        {
          type: "button",
          text: { type: "plain_text", text: "⚙️ Settings" },
          action_id: "show_settings"
        },
        {
          type: "button",
          text: { type: "plain_text", text: "❓ Help" },
          action_id: "show_help"
        }
      ]
    }
  ]
};

Install with Tessl CLI

npx tessl i tessl/npm-slack--types

docs

block-kit.md

calls.md

dialog.md

events.md

index.md

interactive-elements.md

message-attachments.md

message-metadata.md

views.md

tile.json