folders¶

Folders serve as a container for your files and list items.

IFolders¶

Represents a collection of folders. SharePoint webs, lists, and list items have a collection of folders under their properties.

Get folders collection for various SharePoint objects¶

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/items";
import "@pnp/sp/folders";
import "@pnp/sp/lists";

const sp = spfi(...);

// gets web's folders
const webFolders = await sp.web.folders();

// gets list's folders
const listFolders = await sp.web.lists.getByTitle("My List").rootFolder.folders();

// gets item's folders
const itemFolders = await sp.web.lists.getByTitle("My List").items.getById(1).folder.folders();

folderFromServerRelativePath¶

Added in 3.3.0

Utility method allowing you to get an IFolder reference using any SPQueryable as a base and the server relative path to the folder. Helpful when you do not have convenient access to an IWeb to use getFolderByServerRelativePath.

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import { folderFromServerRelativePath } from "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED, URL CANNOT END IN "/"
const url = "/sites/dev/documents/folder4";

// folder is an IFolder and supports all the folder operations
const folder: IFolder = folderFromServerRelativePath(sp.web, url);

// for example
const folderInfo = await folder();
const files = await folder.files();

folderFromAbsolutePath¶

Added in 3.8.0

Utility method allowing you to get an IFile reference using any SPQueryable as a base and an absolute path to the file.

Works across site collections within the same tenant

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import { folderFromAbsolutePath } from "@pnp/sp/folders";

const sp = spfi(...);

const url = "https://tenant.sharepoint.com/sites/dev/documents/folder";

// folder is an IFolder and supports all the folder operations
// Unlike folderFromServerRelativePath, this method must be await'd to resolve folder from absolute Url.
const folder: IFolder = await folderFromAbsolutePath(sp.web, url);

// for example
const folderInfo = await folder();
const files = await folder.files();

folderFromPath¶

Added in 3.8.0

Utility method allowing you to get an IFolder reference using any SPQueryable as a base and an absolute OR server relative path to the file.

Works across site collections within the same tenant

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import { folderFromPath } from "@pnp/sp/folders";

const sp = spfi(...);

const url = "https://tenant.sharepoint.com/sites/dev/documents/folder";

// folder is an IFolder and supports all the folder operations
const folder = folderFromPath(sp.web, url);

// for example
const folderInfo = await folder();

const url2 = "/sites/dev/documents/folder";

// folder is an IFolder and supports all the folder operations
const folder2 = folderFromPath(sp.web, url2);

// for example
const folderInfo2 = await folder2();

add¶

Adds a new folder to collection of folders

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED
const url = "/sites/dev/Shared Documents/MyFolder"

// creates a new folder for web with specified server relative url
const folderAddResult = await sp.web.folders.addUsingPath(url);

getByUrl¶

Gets a folder instance from a collection by folder's name. This call is the equivalent of getting the document libraries root folder. e.g. const listFolders = await sp.web.lists.getByTitle("Documents").rootFolder();

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// pass the name of the document library, cannot include relative paths for subfolders.
const folder = await sp.web.folders.getByUrl("Shared Documents")();

IFolder¶

Represents an instance of a SharePoint folder.

Get a folder object associated with different SharePoint artifacts (web, list, list item)¶

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";
import "@pnp/sp/lists";
import "@pnp/sp/items";

const sp = spfi(...);

// web's folder
const rootFolder = await sp.web.rootFolder();

// list's folder
const listRootFolder = await sp.web.lists.getByTitle("234").rootFolder();

// item's folder
const itemFolder = await sp.web.lists.getByTitle("234").items.getById(1).folder();

getItem¶

Gets list item associated with a folder

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

const folderItem = await sp.web.rootFolder.folders.getByUrl("SiteAssets").folders.getByUrl("My Folder").getItem();

storageMetrics¶

Added in 3.8.0

Gets a set of metrics describing the total file size contained in the folder.

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED
const url = "/sites/dev/shared documents/target";

const metrics = await sp.web.getFolderByServerRelativePath(url).storageMetrics();

// you can also select specific metrics if desired:
const metrics2 = await sp.web.getFolderByServerRelativePath(url).storageMetrics.select("TotalSize")();

move by path¶

It's possible to move a folder to a new destination within the same or a different site collection

If you change the filename during the move operation this is considered an "edit" and the file's modified information will be updated regardless of the "RetainEditorAndModifiedOnMove" setting.

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED - will get "Access is denied" error.
// destination is a server-relative url of a new folder
const destinationUrl = `/sites/my-site/SiteAssets/new-folder`;

await sp.web.rootFolder.folders.getByUrl("SiteAssets").folders.getByUrl("My Folder").moveByPath(destinationUrl, true);

Added in 3.8.0

You can also supply a set of detailed options to better control the move process:

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED - will get "Access is denied" error.
// destination is a server-relative url of a new file
const destinationUrl = `/sites/dev2/SiteAssets/folder`;

await sp.web.getFolderByServerRelativePath("/sites/dev/Shared Documents/folder").moveByPath(destinationUrl, {
    KeepBoth: false,
    RetainEditorAndModifiedOnMove: true,
    ShouldBypassSharedLocks: false,
});

copy by path¶

It's possible to copy a folder to a new destination within the same or a different site collection

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED - will get "Access is denied" error.
// destination is a server-relative url of a new folder
const destinationUrl = `/sites/my-site/SiteAssets/new-folder`;

await sp.web.rootFolder.folders.getByUrl("SiteAssets").folders.getByUrl("My Folder").copyByPath(destinationUrl, true);

Added in 3.8.0

You can also supply a set of detailed options to better control the copy process:

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED - will get "Access is denied" error.
// destination is a server-relative url of a new file
const destinationUrl = `/sites/dev2/SiteAssets/folder`;

await sp.web.getFolderByServerRelativePath("/sites/dev/Shared Documents/folder").copyByPath(destinationUrl, false, {
    KeepBoth: false,
    ResetAuthorAndCreatedOnCopy: true,
    ShouldBypassSharedLocks: false,
});

delete¶

Deletes a folder

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

await sp.web.rootFolder.folders.getByUrl("Shared Documents").delete();

delete with params¶

Deletes a folder with options

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

await sp.web.rootFolder.folders.getByUrl("Shared Documents").deleteWithParams({
                BypassSharedLock: true,
                DeleteIfEmpty: true,
            });

recycle¶

Recycles a folder

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

await sp.web.rootFolder.folders.getByUrl("Shared Documents").recycle();

serverRelativeUrl¶

Gets folder's server relative url

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

const relUrl = await sp.web.rootFolder.folders.getByUrl("SiteAssets").select('ServerRelativeUrl')();

update¶

Updates folder's properties

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

await sp.web.getFolderByServerRelativePath("Shared Documents/Folder2").update({
        "Name": "New name",
    });

contentTypeOrder¶

Gets content type order of a folder

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

const order = await sp.web.getFolderByServerRelativePath("Shared Documents").select('contentTypeOrder')();

folders¶

Gets all child folders associated with the current folder

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

const folders = await sp.web.rootFolder.folders();

files¶

Gets all files inside a folder

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";
import "@pnp/sp/files/folder";

const sp = spfi(...);

// URL CANNOT BE ENCODED
const files = await sp.web.getFolderByServerRelativePath("Shared Documents").files();

listItemAllFields¶

Gets this folder's list item field values

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED
const itemFields = await sp.web.getFolderByServerRelativePath("Shared Documents/My Folder").listItemAllFields();

parentFolder¶

Gets the parent folder, if available

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED
const parentFolder = await sp.web.getFolderByServerRelativePath("Shared Documents/My Folder").parentFolder();

properties¶

Gets this folder's properties

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED
const properties = await sp.web.getFolderByServerRelativePath("Shared Documents/Folder2").properties();

uniqueContentTypeOrder¶

Gets a value that specifies the content type order.

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED
const contentTypeOrder = await sp.web.getFolderByServerRelativePath("Shared Documents/Folder2").select('uniqueContentTypeOrder')();

Rename a folder¶

You can rename a folder by updating FileLeafRef property:

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED
const folder = sp.web.getFolderByServerRelativePath("Shared Documents/My Folder");

const item = await folder.getItem();
const result = await item.update({ FileLeafRef: "Folder2" });

Create a folder with custom content type¶

Below code creates a new folder under Document library and assigns custom folder content type to a newly created folder. Additionally it sets a field of a custom folder content type.

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/items";
import "@pnp/sp/folders";
import "@pnp/sp/lists";

const sp = spfi(...);

// URL CANNOT BE ENCODED
const newFolderResult = await sp.web.rootFolder.folders.getByUrl("Shared Documents").folders.addUsingPath("My New Folder");
const item = await sp.web.rootFolder.folders.getByUrl("Shared Documents").folders.getByUrl(newFolderResult.Name).listItemAllFields();

await sp.web.lists.getByTitle("Documents").items.getById(item.ID).update({
    ContentTypeId: "0x0120001E76ED75A3E3F3408811F0BF56C4CDDD",
    MyFolderField: "field value",
    Title: "My New Folder",
});

addSubFolderUsingPath¶

You can use the addSubFolderUsingPath method to add a folder with some special chars supported

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";
import { IFolder } from "@pnp/sp/folders";

const sp = spfi(...);

// URL CANNOT BE ENCODED and cannot include sub-paths.
const url = "Folder Name";
// add a folder to site assets
const folder: IFolder = await sp.web.rootFolder.folders.getByUrl("SiteAssets").addSubFolderUsingPath(url);

getFolderById¶

You can get a folder by UniqueId from a web.

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";
import { IFolder } from "@pnp/sp/folders";

const sp = spfi(...);

const folderItem = sp.web.lists.getByTitle("My List").items.getById(1).select("UniqueId")()
const folder: IFolder = sp.web.getFolderById(folderItem.UniqueId);

getParentInfos¶

Gets information about folder, including details about the parent list, parent list root folder, and parent web.

import { spfi } from "@pnp/sp";
import "@pnp/sp/webs";
import "@pnp/sp/folders";

const sp = spfi(...);

const folder: IFolder = sp.web.getFolderById("2b281c7b-ece9-4b76-82f9-f5cf5e152ba0");
await folder.getParentInfos();