Microsoft Teams Channel Picker component in Microsoft Graph Toolkit

Article
02/07/2024

You can use the mgt-teams-channel-picker component to enable searches for Microsoft Teams channels associated with a user. The component can search all teams the user has joined, and each channel in those teams.

Example

The following example shows the mgt-teams-channel-picker component. Start searching for a channel or team to see the results render.

HTML
React

Open this example in mgt.dev.

Getting the selected channel

Use the selectedItem property to retrieve the currently selected channel and parent team. This value will be null if no channel has been selected. selectedItem contains two properties: channel (MicrosoftGraph.Channel) and team (MicrosoftGraph.Team).

const channelPicker = document.querySelector("mgt-teams-channel-picker");
console.log(channelPicker.selectedItem.channel);
console.log(channelPicker.selectedItem.team);

Selecting a channel

Use the selectChannelById(channelId: string) method to programmatically select a channel.

Note: the Teams channel picker only supports single channel selection.

const channelPicker = document.querySelector("mgt-teams-channel-picker");
const channelId = "some-channel-id";
channelPicker.selectChannelById(channelId);

Note: The provided channel (and subsequent ID) must belong to a team that the authenticated user has joined.

CSS custom properties

The mgt-teams-channel-picker component defines the following CSS custom properties.

<mgt-teams-channel-picker
  class="teams-channel-picker"
  person-query="me"
></mgt-teams-channel-picker>

.teams-channel-picker {
  --channel-picker-input-border: 2px rgba(255, 255, 255, 0.5) solid; /* sets all input area border */

  --channel-picker-input-background-color: #1f1f1f; /* input area background color */
  --channel-picker-input-background-color-hover: #008394; /* input area border hover color */
  --channel-picker-input-background-color-focus: #0f78d4; /* input area border focus color */

  --channel-picker-dropdown-background-color: brown; /* channel background color */
  --channel-picker-dropdown-item-text-color: #fff;
  --channel-picker-dropdown-item-background-color-hover: #333d47; /* channel or team hover background */
  --channel-picker-dropdown-item-text-color-selected: #0f78d4; /* selected channel background color */

  --channel-picker-color: white; /* input area border focus color */
  --channel-picker-arrow-fill: #ffffff;
  --channel-picker-input-placeholder-text-color: #f1f1f1; /* placeholder text color */
  --channel-picker-input-placeholder-text-color-hover: rgba(
    255,
    255,
    255,
    0.8
  ); /* place holder text focus color */
  --channel-picker-input-placeholder-text-color-focus: rgba(
    255,
    255,
    255,
    0.8
  ); /* place holder text focus color */

  --channel-picker-search-icon-color: yellow;
  --channel-picker-close-icon-color: yellow;
  --channel-picker-down-chevron-color: yellow;
  --channel-picker-up-chevron-color: yellow;
}

To learn more, see styling components.

Events

Event	When is it emitted	Custom data	Cancelable	Bubbles	Works with custom template
`selectionChanged`	Fires when the user makes a change in the selection of a channel	The currently selected item as `{ channel:` channel`, team:` team`}`	No	No	Yes

For more information about handling events, see events.

Templates

mgt-teams-channel-picker supports several templates that you can use to replace certain parts of the component. To specify a template, include a <template> element inside a component and set the data-type to one of the following values.

Data type	Data context	Description
loading	null: no data	The template used to render the state of the picker while making a request to Microsoft Graph is being made.
error	null: no data	The template used if a user search returns no users.

The following example shows how to use the error template.

<mgt-teams-channel-picker>
  <template data-type="error">
    <p>Sorry, no Teams or Channels were found</p>
  </template>
</mgt-teams-channel-picker>

Microsoft Graph permissions

This component uses the following Microsoft Graph APIs and permissions by default. For each API called the user must have at least one of the listed permissions.

Configuration	Permission	API
default	Team.ReadBasic.All, TeamSettings.Read.All, TeamSettings.ReadWrite.All, User.Read.All, User.ReadWrite.All	/me/joinedTeams
default	Team.ReadBasic.All TeamSettings.Read.All, TeamSettings.ReadWrite.All	/teams/${teamId}/photo/$value
default	Channel.ReadBasic.All, ChannelSettings.Read.All, ChannelSettings.ReadWrite.All	/teams/${id}/channels

Authentication

The control uses the global authentication provider described in the authentication documentation.

Cache

The mgt-teams-channel-picker component doesn't cache any data.

Extend for more control

For more complex scenarios or a truly custom UX, this component exposes several protected render* methods for override in component extensions:

Method	Description
renderSelected	Renders the selected team and channel in the input box.
renderInput	Renders the input box.
renderDropdown	Renders the dropdown.
renderDropdownList	Renders the items in the dropdown recursively.
renderItem	Renders a team or a channel in the dropdown list.
renderHighlightedText	Renders the channel text, highlighting the input query.
renderLoading	Renders the loading dropdown state.
renderError	Renders the dropdown error state.

Localization

The control exposes the following variables that can be localized. For details about how to set up localization, see Localizing components.

String name	Default value
closeButtonAriaLabel	`remove the selected channel`
inputPlaceholderText	`Select a channel`
loadingMessage	`Loading...`
noResultsFound	`We didn't find any matches.`
photoFor	`Teams photo for`
teamsChannels	`Teams and channels results`

Share via