Basic Operations

This article describes completing basic operations using the JS core library. It assumes you have added the library to your project either via CDN, bower, or npm package. The API is fluent and matches the structure of the underlying REST API to make it easy to discover the capabilities through intellisense.

Quick note on notation

All of the samples posted below are TypeScript examples. If you are using the library directly in JavaScript they will all still work, with a few modifications.

• Where you see something like pnp.sp.* just replace it with $pnp.sp.*
• Where you see something like:

  import { Web } from "sp-pnp-js";
  let w = new Web("{Site Url"});
  

  use:

  var w = new $pnp.Web("{Site Url}");
  

Read Data

The simplest thing you can do is read data. Below are several examples of reading data. As you can see the get method returns a Promise. For GET operations you must call the get() method to finalize the property chain and execute the request. It is also good practice to include a catch() in your promise handling chain to ensure you track and handle any errors.

import pnp from "sp-pnp-js";

// GET /_api/web
pnp.sp.web.get().then(r => {
    
    console.log(r);
});

// GET /_api/web/lists
pnp.sp.web.lists.get().then(r => {
    
    console.log(r);
});

// GET /_api/web/lists/getByTitle('Tasks')
pnp.sp.web.lists.getByTitle("Tasks").get().then(r => {
    
    console.log(r);
});

// GET /_api/web/lists/getByTitle('Tasks')/items
pnp.sp.web.lists.getByTitle("Tasks").items.get().then(r => {
    
    console.log(r);
});

// GET /_api/web/lists/getByTitle('Tasks')/items(1)
pnp.sp.web.lists.getByTitle("Tasks").items.getById(1).get().then(r => {
    
    console.log(r);
});

OData Operators

The library also supports the OData operations select and expand for instances (such as a list or an item) as well we the select, filter, expand, orderBy, skip, and top operations for collections (collection of lists, or items). Some examples are provided below. Remember, the get() method call must always be the last call in your chain as that executes the request.

import pnp from "sp-pnp-js";

pnp.sp.web.select("Title", "AllProperties").expand("AllProperties").get().then(r => {
    
    console.log(r);
});

pnp.sp.web.lists.getByTitle("Tasks").items.filter("Title eq 'Value'").top(2).orderBy("Modified").get().then(r => {
    
    console.log(r);
});

// Getting the second "page" of results from the top query
pnp.sp.web.lists.getByTitle("Tasks").items.filter("Title eq 'Value'").skip(2).top(2).orderBy("Modified").get().then(r => {
    
    console.log(r);
});

Add and Update Values

The next step is to update or add to SharePoint and the API helps with this as well. One of the most common operations is adding/updating list items, shown here. The properties you pass in should match the field names of the list item you want to add.

import pnp from "sp-pnp-js";

pnp.sp.web.lists.getByTitle("Tasks").items.add({
    Title: "My Item Title"
}).then(r => {
    
    // this result will have two properties "data" and "item"
    // data is what was returned from SharePoint after the add operation
    // and item is an object of type item representing the REST query to that item
    // so you can immediately chain off that

    console.log(r);

    // this will add an attachment to the item we just created
    r.item.attachmentFiles.add("file.txt", "Here is some file content.");

});

// Getting the second "page" of results from the top query
pnp.sp.web.lists.getByTitle("Tasks").items.getById(1).update({
    Title: "My New Item Title"
}).then(r => {
    
    // this result will have two properties "data" and "item"
    // data is what was returned from SharePoint after the update operation
    // and item is an object of type item representing the REST query to that item
    // so you can immediately chain off that

    console.log(r);
});