How to Add a SharePoint Document Library as a Tab in Microsoft Teams with PowerShell

Introduction

Adding a SharePoint document library as a tab in Microsoft Teams is a common requirement for collaboration scenarios. While Teams provides an out-of-the-box (OOTB) experience for this, automating the process via PowerShell or Microsoft Graph can be tricky due to limitations.

Thanks to Tiago Duarte through the discussion within the bug he raised , he found out a solution for it using Ms Graph PowerShell and I attempted to achieve same using PnP PowerShell. Read more from [BUG] Add-PnPTeamsTab with DocumentLibrary type creates a hidden tab.

Scenario

Goal:
Programmatically add a SharePoint document library as a tab in a Teams channel.

Microsoft has deprecated the “DocumentLibrary” tab type due to inconsistencies and errors. The recommended approach is to use a custom tab with a new Teams App ID and a specific content URL format, which closely mimics the OOTB experience.

PowerShell Example (Microsoft Graph)

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "Group.ReadWrite.All","TeamsTab.ReadWriteForTeam","TeamsTab.ReadWrite.All","Sites.Read.All"

$siteUrl = "https://contoso.sharepoint.com/sites/YourSite"
$lib = "Documents"  # Specify the library name

$params = @{
    displayName = $lib
    "teamsApp@odata.bind" = "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/2a527703-1f6f-4559-a332-d8a7d288cd88"
    configuration = @{
        entityId = ""
        contentUrl = ($siteUrl + '/_layouts/15/filebrowser.aspx?app=teamsfile&scenario=teamsPage&auth=none&fileBrowser=' + [System.Web.HttpUtility]::UrlEncode('{"sdk":"1.0","entry":{"sharePoint":{"byPath":{"folder":"' + $siteUrl + '/' + $lib + '"}}}}') + '&theme={theme}')
        websiteUrl = $null
        removeUrl = $null
    }
}

# Get the groupId and channelId
$group = Get-MgGroup -Filter "displayName eq 'YourTeamName'" -ConsistencyLevel eventual
$groupId = $group.Id
$channel = Get-MgTeamChannel -TeamId $groupId | Where-Object { $_.DisplayName -eq 'General' }
$channelId = $channel.Id

New-MgTeamChannelTab -TeamId $groupId -ChannelId $channelId -BodyParameter $params | Out-Null
Write-Host "$lib tab created."

PnP PowerShell Example

$siteUrl = "https://contoso.sharepoint.com/sites/YourSite"
$lib = "Documents"  # Specify the library name

$ContentUrl = ($siteUrl + '/_layouts/15/filebrowser.aspx?app=teamsfile&scenario=teamsPage&auth=none&fileBrowser=' + [System.Web.HttpUtility]::UrlEncode('{"sdk":"1.0","entry":{"sharePoint":{"byPath":{"folder":"' + $siteUrl + '/' + $lib + '"}}}}') + '&theme={theme}')
Add-PnPTeamsTab -Team "YourTeamName" -Channel "General" -DisplayName $lib -Type Custom -ContentUrl $ContentUrl -TeamsAppId "2a527703-1f6f-4559-a332-d8a7d288cd88"

CLI for Microsoft 365


# Login to Microsoft 365 CLI with service principal
m365 login --appId "xxx" --tenant "xxx" 

$siteUrl = "https://4g6zf4.sharepoint.com/sites/Retail"
$lib = "test"  # Specify the library name
$team = "Retail"
$channel = "General"
$displayName = "test"
# Get teamId using CLI
$teamId = m365 teams team get --name $team --output json | ConvertFrom-Json | Select-Object -ExpandProperty id
# Get channelId using CLI
$channelId = m365 teams channel get --teamId $teamId --name $channel --output json | ConvertFrom-Json | Select-Object -ExpandProperty id

m365 teams tab add --teamId $teamId --channelId $channelId --appId "2a527703-1f6f-4559-a332-d8a7d288cd88" --appName $displayName --contentUrl "https://4g6zf4.sharepoint.com/sites/Retail/_layouts/15/filebrowser.aspx?app=teamsfile&scenario=teamsPage&auth=none&fileBrowser=%7b%22sdk%22%3a%221.0%22%2c%22entry%22%3a%7b%22sharePoint%22%3a%7b%22byPath%22%3a%7b%22folder%22%3a%22https%3a%2f%2f4g6zf4.sharepoint.com%2fsites%2fRetail%2ftest%22%7d%7d%7d%7d&theme={theme}"

Output of script tab added

Notes:

  • The fileBrowser property value must be URL-encoded.
  • The folder parameter can be the absolute or relative URL of the library.
  • The new Teams App ID (2a527703-1f6f-4559-a332-d8a7d288cd88) is required for the modern experience.

Example Output

The tab is added correctly.

tab added

Other tried methods by Tago Duarte with his findings

Method 1: Using PnP PowerShell with SharePointPageAndList Type

Add-PnPTeamsTab -Team [group-id] -Channel "General" -DisplayName "Storage" -Type SharePointPageAndList -WebSiteUrl "https://contoso/Storage"

Behavior:

  • Success: Tab is added and library content is shown.
  • Limitation: The tab appears as a content frame, which looks and behaves differently from the OOTB “Document Library” tab.

Method 2: Using PnP PowerShell with DocumentLibrary Type

Add-PnPTeamsTab -Team [group-id] -Channel "General" -DisplayName "Storage" -Type DocumentLibrary -ContentUrl "https://contoso/Storage"

Behavior:

  • Command runs without errors, tab is created, but it is not visible in the Teams UI.
  • The tab appears in the list when running Get-PnPTeamsTab, but is hidden in the Teams client.

Method 3: Microsoft Graph API

Example

$params = @{
    displayName = "Storage"
    "teamsApp@odata.bind" = "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/com.microsoft.teamspace.tab.files.sharepoint"
    configuration = @{
        entityId = ""
        contentUrl = ($siteUrl + "/" + "Storage")
        websiteUrl = $null
        removeUrl = $null
    }
}
New-MgTeamChannelTab -TeamId $groupId -ChannelId $channel.Id -BodyParameter $params

Behavior:

  • Tab is created and listed via PowerShell, but not visible in Teams.
  • When accessed via Teams for the Web, the tab appears “unconfigured” until clicked, after which it configures itself and becomes visible in the Teams client.
  • The tab type switches from “DocumentLibrary” to “SharePoint” after configuration.

Important Update: Document Library Tab Deprecation

As of July 2025, Microsoft has deprecated the “DocumentLibrary” tab type due to inconsistencies and errors. The documentation is being updated, and it is recommended not to create new tabs of this type via Graph or PowerShell as per issue Not able to see Document library content inside MS Teams tab created using Graph API.

Summary Table

MethodTab Visible in TeamsOOTB ExperienceRecommended
Custom Tab with New App ID (Current)✅✅✅
SharePointPageAndList (PnP PowerShell)✅❌❌
DocumentLibrary (PnP PowerShell/Graph)❌❌❌

References

[BUG] Add-PnPTeamsTab with DocumentLibrary type creates a hidden tab

Not able to see Document library content inside MS Teams tab created using Graph API

Add-PnPTeamsTab