Visit the Plugins section to learn more about developing Mattermost plugins and our recommended developer workflow for Mattermost plugins.
The PluginClass interface defines two methods used by the Mattermost Web App to initialize and uninitialize your plugin:
class PluginClass {
/**
* initialize is called by the webapp when the plugin is first loaded.
* Receives the following:
* - registry - an instance of the registry tied to your plugin id
* - store - the Redux store of the web app.
*/
initialize(registry, store)
/**
* uninitialize is called by the webapp if your plugin is uninstalled
*/
uninitialize()
}
Your plugin should implement this class and register it using the global registerPlugin method defined on the window by the webapp:
window.registerPlugin('myplugin', new PluginClass());
Use the provided registry to register components, post type overrides and callbacks. Use the store to access the global state of the web app, but note that you should use the registry to register any custom reducers your plugin might require.
The entry point index.js of your application might contain:
import UserPopularity from './components/profile_popover/user_popularity';
import SomePost from './components/some_post';
import MenuIcon from './components/menu_icon';
import {openExampleModal} from './actions';
class PluginClass {
initialize(registry, store) {
registry.registerPopoverUserAttributesComponent(
UserPopularity,
);
registry.registerPostTypeComponent(
'custom_somepost',
SomePost,
);
registry.registerMainMenuAction(
'Plugin Menu Item',
() => store.dispatch(openExampleModal()),
mobile_icon: MenuIcon,
);
}
uninitialize() {
// No clean up required.
}
}
window.registerPlugin('myplugin', new PluginClass());
This will add a custom UserPopularity component to the profile popover, render a custom SomePost component for any post with the type custom_somepost, and insert a custom main menu item.
An instance of the plugin registry is passed to each plugin via the initialize callback.
/**
* Register a component at the root of the channel view of the app.
* Accepts a React component. Returns a unique identifier.
*/
registerRootComponent([component])
/**
* Register a component in the user attributes section of the profile popover (hovercard), below the default user attributes.
* Accepts a React component. Returns a unique identifier.
*/
registerPopoverUserAttributesComponent([component])
/**
* Register a component in the user actions of the profile popover (hovercard), below the default actions.
* Accepts a React component. Returns a unique identifier.
*/
registerPopoverUserActionsComponent([component])
/**
* Register a component fixed to the top of the left-hand channel sidebar.
* Accepts a React component. Returns a unique identifier.
*/
registerLeftSidebarHeaderComponent([component])
/**
* Register a component fixed to the bottom of the team sidebar. Does not render if
* user is only on one team and the team sidebar is not shown.
* Accepts a React component. Returns a unique identifier.
*/
registerBottomTeamSidebarComponent([component])
/**
* Register a component fixed to the bottom of the post message.
* Accepts a React component. Returns a unique identifier.
*/
registerPostMessageAttachmentComponent([component])
/**
* Register a component to show as a tooltip when a user hovers on a link in a post.
* Accepts a React component. Returns a unique identifier.
* The component will be passed the following props:
* - href - The URL for this link
* - show - A boolean used to signal that the user is currently hovering over this link. Use this value to initialize your component when this boolean is true for the first time, using `componentDidUpdate` or `useEffect`.
*/
registerLinkTooltipComponent([component])
/**
* Register a component fixed to the bottom of the create new channel modal and also registers a callback function to be called after
* the channel has been succesfully created
* Accepts a React component. Returns a unique identifier.
*/
registerActionAfterChannelCreation([component action])
/**
* Add a button to the channel header. If there are more than one buttons registered by any
* plugin, a dropdown menu is created to contain all the plugin buttons.
* Accepts the following:
* - icon - React element to use as the button's icon
* - action - a function called when the button is clicked, passed the channel and channel member as arguments
* - dropdownText - string or React element shown for the dropdown button description
* - tooltipText - string or React element shown for tooltip appear on hover
*/
registerChannelHeaderButtonAction([icon action dropdownText tooltipText])
/**
* Add a button to the channel intro message.
* Accepts the following:
* - icon - React element to use as the button's icon
* - action - a function called when the button is clicked, passed the channel and channel member as arguments
* - text - a localized string or React element to use as the button's text
*/
registerChannelIntroButtonAction([icon action text])
/**
* Add a "call button" to the channel header. If there is more than one button registered by any
* plugin, a dropdown menu is created to contain all the call plugin buttons.
* Accepts the following:
* - button - A React element to use as the main button to be displayed in case of a single registration.
* - dropdownButton -A React element to use as the dropdown button to be displayed in case of multiple registrations.
* - action - A function called when the button is clicked, passed the channel and channel member as arguments.
* Returns an unique identifier
* Minimum required version: 6.5
*/
registerCallButtonAction([button dropdownButton action])
/**
* Register a component to render a custom body for posts with a specific type.
* Custom post types must be prefixed with 'custom_'.
* Custom post types can also apply for ephemeral posts.
* Accepts a string type and a component.
* Returns a unique identifier.
*/
registerPostTypeComponent([type component])
/**
* Register a component to render a custom body for post cards with a specific type.
* Custom post types must be prefixed with 'custom_'.
* Accepts a string type and a component.
* Returns a unique identifier.
*/
registerPostCardTypeComponent([type component])
/**
* Register a component to render a custom embed preview for post links.
* Accepts the following:
* - match - A function that receives the embed object and returns a
* boolean indicating if the plugin is able to process it.
* The embed object contains the embed `type`, the `url` of the post link
* and in some cases, a `data` object with information related to the
* link (the opengraph or the image details, for example).
* - component - The component that renders the embed view for the link
* - toggleable - A boolean indicating if the embed view should be collapsable
* Returns a unique identifier.
*/
registerPostWillRenderEmbedComponent([match component toggleable])
/**
* Register a main menu list item by providing some text and an action function.
* Accepts the following:
* - text - A string or React element to display in the menu
* - action - A function to trigger when component is clicked on
* - mobileIcon - A React element to display as the icon in the menu in mobile view
* Returns a unique identifier.
*/
registerMainMenuAction([text action mobileIcon])
/**
* Register a channel menu list item by providing some text and an action function.
* Accepts the following:
* - text - A string or React element to display in the menu
* - action - A function that receives the channelId and is called when the menu items is clicked.
* - shouldRender - A function that receives the state before the
* component is about to render, allowing for conditional rendering.
* Returns a unique identifier.
*/
registerChannelHeaderMenuAction([text action shouldRender])
/**
* Register a files dropdown list item by providing some text and an action function.
* Accepts the following:
* - match - A function that receives the fileInfo and returns a boolean indicating if the plugin is able to process it.
* - text - A string or React element to display in the menu
* - action - A function that receives the fileInfo and is called when the menu items is clicked.
* Returns a unique identifier.
*/
registerFileDropdownMenuAction([match text action])
/**
* Register a user guide dropdown list item by providing some text and an action function.
* Accepts the following:
* - text - A string or React element to display in the menu
* - action - A function that receives the fileInfo and is called when the menu items is clicked.
* Returns a unique identifier.
*/
registerUserGuideDropdownMenuAction([text action])
/**
* Register a component to the add to the post message menu shown on hover.
* Accepts a React component. Returns a unique identifier.
*/
registerPostActionComponent([component])
/**
* Register a component to the add to the post text editor menu.
* Accepts a React component. Returns a unique identifier.
*/
registerPostEditorActionComponent([component])
/**
* Register a component to the add to the code block header.
* Accepts a React component. Returns a unique identifier.
*/
registerCodeBlockActionComponent([component])
/**
* Register a component to the add to the new messages separator.
* Accepts a React component. Returns a unique identifier.
*/
registerNewMessagesSeparatorActionComponent([component])
/**
* Register a post menu list item by providing some text and an action function.
* Accepts the following:
* - text - A string or React element to display in the menu
* - action - A function to trigger when component is clicked on
* - filter - A function whether to apply the plugin into the post' dropdown menu
* Returns a unique identifier.
*/
registerPostDropdownMenuAction([text action filter])
/**
* Register a post sub menu list item by providing some text and an action function.
* Accepts the following:
* - text - A string or React element to display in the menu
* - action - A function to trigger when component is clicked on
* - filter - A function whether to apply the plugin into the post' dropdown menu
*
* Returns a unique identifier for the root submenu, and a function to register submenu items.
* At this time, only one level of nesting is allowed to avoid rendering issue in the RHS.
*/
registerPostDropdownSubMenuAction([text action filter])
/**
* Register a component at the bottom of the post dropdown menu.
* Accepts a React component. Returns a unique identifier.
*/
registerPostDropdownMenuComponent([component])
/**
* Register a file upload method by providing some text, an icon, and an action function.
* Accepts the following:
* - icon - JSX element to use as the button's icon
* - text - A string or JSX element to display in the file upload menu
* - action - A function to trigger when the menu item is selected.
* Returns a unique identifier.
*/
registerFileUploadMethod([icon action text])
/**
* Register a hook to intercept file uploads before they take place.
* Accepts a function to run before files get uploaded. Receives an array of
* files and a function to upload files at a later time as arguments. Must
* return an object that can contain two properties:
* - message - An error message to display, leave blank or null to display no message
* - files - Modified array of files to upload, set to null to reject all files
* Returns a unique identifier.
*/
registerFilesWillUploadHook([hook])
/**
* Unregister a component, action or hook using the unique identifier returned after registration.
* Accepts a string id.
* Returns undefined in all cases.
*/
unregisterComponent([componentId])
/**
* Unregister a component that provided a custom body for posts with a specific type.
* Accepts a string id.
* Returns undefined in all cases.
*/
unregisterPostTypeComponent([componentId])
/**
* Register a reducer against the Redux store. It will be accessible in redux state
* under "state['plugins-<yourpluginid>']"
* Accepts a reducer. Returns undefined.
*/
registerReducer([reducer])
/**
* Register a handler for WebSocket events.
* Accepts the following:
* - event - the event type, can be a regular server event or an event from plugins.
* Plugin events will have "custom_<pluginid>_" prepended
* - handler - a function to handle the event, receives the event message as an argument
* Returns undefined.
*/
registerWebSocketEventHandler([event handler])
/**
* Unregister a handler for a custom WebSocket event.
* Accepts a string event type.
* Returns undefined.
*/
unregisterWebSocketEventHandler([event])
/**
* Register a handler that will be called when the app reconnects to the
* internet after previously disconnecting.
* Accepts a function to handle the event. Returns undefined.
*/
registerReconnectHandler([handler])
/**
* Unregister a previously registered reconnect handler.
* Returns undefined.
*/
unregisterReconnectHandler()
/**
* Register a hook that will be called when a message is posted by the user before it
* is sent to the server. Accepts a function that receives the post as an argument.
*
* To reject a post, return an object containing an error such as
* {error: {message: 'Rejected'}}
* To modify or allow the post without modification, return an object containing the post
* such as
* {post: {...}}
*
* If the hook function is asynchronous, the message will not be sent to the server
* until the hook returns.
*/
registerMessageWillBePostedHook([hook])
/**
* Register a hook that will be called when a slash command is posted by the user before it
* is sent to the server. Accepts a function that receives the message (string) and the args
* (object) as arguments.
* The args object is:
* {
* channel_id: channelId,
* team_id: teamId,
* root_id: rootId,
* }
*
* To reject a command, return an object containing an error:
* {error: {message: 'Rejected'}}
* To ignore a command, return an empty object (to prevent an error from being displayed):
* {}
* To modify or allow the command without modification, return an object containing the new message
* and args. It is not likely that you will need to change the args, so return the object that was provided:
* {message: {...}, args}
*
* If the hook function is asynchronous, the command will not be sent to the server
* until the hook returns.
*/
registerSlashCommandWillBePostedHook([hook])
/**
* Register a hook that will be called before a message is formatted into Markdown.
* Accepts a function that receives the unmodified post and the message (potentially
* already modified by other hooks) as arguments. This function must return a string
* message that will be formatted.
* Returns a unique identifier.
*/
registerMessageWillFormatHook([hook])
/**
* Register a component to override file previews. Accepts a function to run before file is
* previewed and a react component to be rendered as the file preview.
* - override - A function to check whether preview needs to be overridden. Receives fileInfo and post as arguments.
* Returns true is preview should be overridden and false otherwise.
* - component - A react component to display instead of original preview. Receives fileInfo and post as props.
* Returns a unique identifier.
* Only one plugin can override a file preview at a time. If two plugins try to override the same file preview, the first plugin will perform the override and the second will not. Plugin precedence is ordered alphabetically by plugin ID.
*/
registerFilePreviewComponent([override component])
/**
* Register a admin console definitions override function
* Note that this is a low-level interface primarily meant for internal use, and is not subject
* to semver guarantees. It may change in the future.
* Accepts the following:
* - func - A function that recieve the admin console config definitions and return a new
* version of it, which is used for build the admin console.
* Each plugin can register at most one admin console plugin function, with newer registrations
* replacing older ones.
*/
registerAdminConsolePlugin([func])
/**
* Unregister a previously registered admin console definition override function.
* Returns undefined.
*/
unregisterAdminConsolePlugin()
/**
* Register a custom React component to manage the plugin configuration for the given setting key.
* Accepts the following:
* - key - A key specified in the settings_schema.settings block of the plugin's manifest.
* - component - A react component to render in place of the default handling.
* - options - Object for the following available options to display the setting:
* showTitle - Optional boolean that if true the display_name of the setting will be rendered
* on the left column of the settings page and the registered component will be displayed on the
* available space in the right column.
*/
registerAdminConsoleCustomSetting([key component options])
/**
* Register a custom React component to render as a section in the plugin configuration page.
* Accepts the following:
* - key - A key specified in the settings_schema.sections block of the plugin's manifest.
* - component - A react component to render in place of the default handling.
*/
registerAdminConsoleCustomSection([key component])
/**
* Register a Right-Hand Sidebar component by providing a title for the right hand component.
* Accepts the following:
* - component - A react component to display in the Right-Hand Sidebar.
* - title - A string or JSX element to display as a title for the RHS.
* Returns:
* - id: a unique identifier
* - showRHSPlugin: the action to dispatch that will open the RHS.
* - hideRHSPlugin: the action to dispatch that will close the RHS
* - toggleRHSPlugin: the action to dispatch that will toggle the RHS
*/
registerRightHandSidebarComponent([component title])
/**
* Register a Needs Team component by providing a route past /:team/:pluginId/ to be displayed at.
* Accepts the following:
* - route - The route to be displayed at.
* - component - A react component to display.
* Returns:
* - id: a unique identifier
*/
registerNeedsTeamRoute([route component])
/**
*/
registerProduct([baseURL switcherIcon switcherText switcherLinkURL mainComponent headerCentreComponent headerRightComponent showTeamSidebar showAppBar wrapped publicComponent])
/**
* Register a hook that will be called when a message is edited by the user before it
* is sent to the server. Accepts a function that receives the post as an argument.
*
* To reject a post, return an object containing an error such as
* {error: {message: 'Rejected'}}
* To modify or allow the post without modification, return an object containing the post
* such as
* {post: {...}}
*
* If the hook function is asynchronous, the message will not be sent to the server
* until the hook returns.
*/
registerMessageWillBeUpdatedHook([hook])
/**
* INTERNAL: Subject to change without notice.
* Register a component to render in the LHS next to a channel's link label.
* All parameters are required.
* Returns a unique identifier.
*/
registerSidebarChannelLinkLabelComponent([component])
/**
* INTERNAL: Subject to change without notice.
* Register a component to render in channel's center view, in place of a channel toast.
* All parameters are required.
* Returns a unique identifier.
*/
registerChannelToastComponent([component])
/**
* INTERNAL: Subject to change without notice.
* Register a global component at the root of the app that survives across product switches.
* All parameters are required.
* Returns a unique identifier.
*/
registerGlobalComponent([component])
/**
*/
registerAppBarComponent([iconUrl action tooltipText supportedProductIds rhsComponent rhsTitle])
/**
* INTERNAL: Subject to change without notice.
* Register a handler to retrieve stats that will be displayed on the system console
* Accepts the following:
* - handler - Func to be called to retrieve the stats from plugin api. It must be type PluginSiteStatsHandler.
* Returns undefined
*/
registerSiteStatisticsHandler([handler])
/**
* Register a hook to intercept desktop notifications before they occur.
* Accepts a function to run before the desktop notification is triggered.
* The function has the following signature:
* (post: Post, msgProps: NewPostMessageProps, channel: Channel,
* teamId: string, args: DesktopNotificationArgs) => Promise<{
* error?: string;
* args?: DesktopNotificationArgs;
* }>)
*
* DesktopNotificationArgs is the following type:
* export type DesktopNotificationArgs = {
* title: string;
* body: string;
* silent: boolean;
* soundName: string;
* url: string;
* notify: boolean;
* };
*
* To stop a desktop notification and allow subsequent hooks to process the notification, return:
* {args: {...args, notify: false}}
* To enable a desktop notification and allow subsequent hooks to process the notification, return:
* {args: {...args, notify: true}}
* To stop a desktop notification and prevent subsequent hooks from processing the notification, return either:
* {error: 'log this error'}, or {}
* To allow subsequent hooks to process the notification, return:
* {args}, or null or undefined (thanks js)
*
* The args returned by the hook will be used as the args for the next hook, until all hooks are
* completed. The resulting args will be used as the arguments for the `notifyMe` function.
*
* Returns a unique identifier.
*/
registerDesktopNotificationHook([hook])
/**
* Register a schema for user settings. This will show in the user settings modals
* and all values will be stored in the preferences with cateogry pp_${pluginId} and
* the name of the setting.
*
* The settings definition can be found in /src/types/plugins/user_settings.ts
*
* Malformed settings will be filtered out.
*/
registerUserSettings([setting])In Mattermost, users are able to set custom themes that change the color scheme of the UI. It’s important that plugins have access to a user’s theme so that they can set their styling to match and not look out of place.
Every pluggable component in the web app will have the theme object as a prop.
The colors are exposed via CSS variables as well.
The theme object has the following properties:
| Property | CSS Variable | Description |
|---|---|---|
| sidebarBg | –sidebar-bg | Background color of the left-hand sidebar |
| sidebarText | –sidebar-text | Color of text in the left-hand sidebar |
| sidebarUnreadText | –sidebar-unread-text | Color of text for unread channels in the left-hand sidebar |
| sidebarTextHoverBg | –sidebar-text-hover-bg | Background color of channels when hovered in the left-hand sidebar |
| sidebarTextActiveBorder | –sidebar-text-active-border | Color of the selected indicator channel indicator in the left-hand siebar |
| sidebarTextActiveColor | –sidebar-text-active-color | Color of the text for the selected channel in the left-hand sidebar |
| sidebarHeaderBg | –sidebar-header-bg | Background color of the left-hand sidebar header |
| sidebarHeaderTextColor | –sidebar-header-text-color | Color of text in the left-hand sidebar header |
| onlineIndicator | –online-indicator | Color of the online status indicator |
| awayIndicator | –away-indicator | Color of the away status indicator |
| dndIndicator | –dnd-indicator | Color of the do not disturb status indicator |
| mentionBg | –mention-bg | Background color for mention jewels in the left-hand sidebar |
| mentionColor | –mention-color | Color of text for mention jewels in the left-hand sidebar |
| centerChannelBg | –center-channel-bg | Background color of channels, right-hand sidebar and modals/popovers |
| centerChannelColor | –center-channel-color | Color of text in channels, right-hand sidebar and modals/popovers |
| newMessageSeparator | –new-message-separator | Color of the new message separator in channels |
| linkColor | –link-color | Color of text for links |
| buttonBg | –button-bg | Background color of buttons |
| buttonColor | –button-color | Color of text for buttons |
| errorTextColor | –error-text | Color of text for errors |
| mentionHighlightBg | –mention-highlight-bg | Background color of mention highlights in posts |
| mentionHighlightLink | –mention-highlight-link | Color of text for mention links in posts |
| codeTheme | NA | Code block theme, either ‘github’, ‘monokai’, ‘solarized-dark’ or ‘solarized-light’ |
The web app exposes a number of exported libraries and functions on the window object for plugins to use. To avoid bloating your plugin, we recommend depending on these using Webpack externals or importing them manually from the window. Below is a list of the exposed libraries and functions:
| Library | Exported Name | Description |
|---|---|---|
| react | window.React | ReactJS |
| react-dom | window.ReactDOM | ReactDOM |
| redux | window.Redux | Redux |
| react-redux | window.ReactRedux | React bindings for Redux |
| react-bootstrap | window.ReactBootstrap | Bootstrap for React |
| prop-types | window.PropTypes | PropTypes |
| post-utils | window.PostUtils | Mattermost post utility functions (see below) |
Contains the following post utility functions:
formatText(text, options) Performs formatting of text including Markdown, highlighting mentions and search terms and converting URLs, hashtags, @mentions and ~channels to links by taking a string and returning a string of formatted HTML.
text - String of text to format, e.g. a post’s message.options - (Optional) An object containing the following formatting optionssearchTerm - If specified, this word is highlighted in the resulting HTML. Defaults to nothing.mentionHighlight - Specifies whether or not to highlight mentions of the current user. Defaults to true.mentionKeys - A list of mention keys for the current user to highlight.singleline - Specifies whether or not to remove newlines. Defaults to false.emoticons - Enables emoticon parsing with a data-emoticon attribute. Defaults to true.markdown - Enables markdown parsing. Defaults to true.siteURL - The origin of this Mattermost instance. If provided, links to channels and posts will be replaced with internal links that can be handled by a special click handler.atMentions - Whether or not to render “@” mentions into spans with a data-mention attribute. Defaults to false.channelNamesMap - An object mapping channel display names to channels. If channelNamesMap and team are provided, ~channel mentions will be replaced with links to the relevant channel.team - The current team object.proxyImages - If specified, images are proxied. Defaults to false.messageHtmlToComponent(html, isRHS, options) Converts HTML to React components.
html - String of HTML to convert to React components.isRHS - Boolean indicating if the resulting components are to be displayed in the right-hand sidebar. Has some minor effects on how UI events are triggered for components in the RHS.options - (Optional) An object containing optionsmentions - If set, mentions are replaced with the AtMention component. Defaults to true.emoji - If set, emoji text is replaced with the PostEmoji component. Defaults to true.images - If set, markdown images are replaced with the PostMarkdown component. Defaults to true.latex - If set, latex is replaced with the LatexBlock component. Defaults to true.A short usage example of a PostType component using the post utility functions to format text.
import React from 'react'; // accessed through webpack externals
import PropTypes from 'prop-types';
const PostUtils = window.PostUtils; // must be accessed through `window`
export default class PostTypeFormatted extends React.PureComponent {
// ...
render() {
const post = this.props.post;
const formattedText = PostUtils.formatText(post.message); // format the text
return (
<div>
{'Formatted text: '}
{PostUtils.messageHtmlToComponent(formattedText)} // convert the html to components
</div>
);
}
}