Working With: Items

GET

Getting items from a list is one of the basic actions that most applications require. This is made easy through the library and the following examples demonstrate these actions.

Basic Get

import pnp from "sp-pnp-js";

// get all the items from a list
pnp.sp.web.lists.getByTitle("My List").items.get().then((items: any[]) => {

    console.log(items);
});

// get a specific item by id
pnp.sp.web.lists.getByTitle("My List").items.getById(1).get().then((item: any) => {

    console.log(items);
});

// use odata operators for more efficient queries
pnp.sp.web.lists.getByTitle("My List").items.select("Title", "Description").top(5).orderBy("Modified", true).get().then((items: any[]) => {

    console.log(items);
});

Retrieving Lookup Fields

When working with lookup fields you need to use the expand operator along with select to get the related fields from the lookup column. This works for both the items collection and item instances.

pnp.sp.web.lists.getByTitle("LookupList").items.select("Title", "Lookup/Title", "Lookup/ID").expand("Lookup").get().then((items: any[]) => {

    console.log(items);
});

pnp.sp.web.lists.getByTitle("LookupList").items.getById(1).select("Title", "Lookup/Title", "Lookup/ID").expand("Lookup").get().then((item: any) => {

    console.log(item);
});

Add Items

There are several ways to add items to a list. The simplest just uses the add method of the items collection passing in the properties as a plain object.

import { default as pnp, ItemAddResult } from "sp-pnp-js";

// add an item to the list
pnp.sp.web.lists.getByTitle("My List").items.add({
    Title: "Title",
    Description: "Description"
}).then((iar: ItemAddResult) => {

    console.log(iar);
});

Content Type

You can also set the content type id when you create an item as shown in the example below:

pnp.sp.web.lists.getById("4D5A36EA-6E84-4160-8458-65C436DB765C").items.add({
    Title: "Test 1",
    ContentTypeId: "0x01030058FD86C279252341AB303852303E4DAF"
});

User Fields

There are two types of user fields, those that allow a single value and those that allow multiple. For both types you first need to determine the Id field name, which you can do by doing a GET REST request on an existing item. Typically the value will be the user field internal name with "Id" appended. So in our example we have two fields User1 and User2 so the Id fields are User1Id and User2Id.

Next you need to remember there are two types of user fields, those that take a single value and those that allow multiple - these are updated in different ways. For single value user fields you supply just the user's id. For multiple value fields you need to supply an object with a "results" property and an array. Examples for both are shown below.

pnp.sp.web.lists.getByTitle("PeopleFields").items.add({
    Title: Util.getGUID(),
    User1Id: 9, // allows a single user
    User2Id: { results: [16] }, // allows multiple users
}).then(i => {
    console.log(i);
});

Add Multiple Items

import pnp from "sp-pnp-js";

let list = pnp.sp.web.lists.getByTitle("rapidadd");

list.getListItemEntityTypeFullName().then(entityTypeFullName => {

    let batch = pnp.sp.web.createBatch();

    list.items.inBatch(batch).add({ Title: "Batch 6" }, entityTypeFullName).then(b => {

        console.log(b);

    });

    list.items.inBatch(batch).add({ Title: "Batch 7" }, entityTypeFullName).then(b => {

        console.log(b);

    });

    batch.execute().then(d => console.log("Done"));
});

Update

The update method is very similar to the add method in that it takes a plain object representing the fields to update. The property names are the internal names of the fields. If you aren't sure you can always do a get request for an item in the list and see the field names that come back - you would use these same names to update the item.

import pnp from "sp-pnp-js";

let list = pnp.sp.web.lists.getByTitle("MyList");

list.items.getById(1).update({
    Title: "My New Title",
    Description: "Here is a new description"
}).then(i => {
    console.log(i);
});

Getting and updating a collection using filter

import pnp from "sp-pnp-js";

// you are getting back a collection here
pnp.sp.web.lists.getByTitle("MyList").items.top(1).filter("Title eq 'A Title'").get().then((items: any[]) => {

    // see if we got something
    if (items.length > 0) {

        pnp.sp.web.lists.getByTitle("MyList").items.getById(items[0].Id).update({
            Title: "Updated Title",
        }).then(result => {

            // here you will have updated the item
            console.log(JSON.stringify(result));
        });
    }
});

Delete

Delete is as simple as calling the .delete method. It optionally takes an eTag if you need to manage concurrency.

import pnp from "sp-pnp-js";

let list = pnp.sp.web.lists.getByTitle("MyList");

list.items.getById(1).delete().then(_ => {});