SP.ListItem object

Article
08/29/2016

Represents an item or row in a list.

Applies to: apps for SharePoint | SharePoint Foundation 2013 | SharePoint Server 2013

var object = new SP.ListItem()

Members

The ListItem object has the following members.

Constructor

The ListItem object has the following constructor.

Constructor	Description
ListItem	Initializes a new instance of the SP.ListItem object.

Methods

The ListItem object has the following methods.

Method	Description
deleteObject	Deletes the list item.
getUserEffectivePermissions	Gets the effective permissions that a specified user has on the list item.
getWOPIFrameUrl	Gets the full URL to the SharePoint frame page that initiates the SP.Utilities.SPWOPIFrameAction object with the WOPI application associated with the list item.
initNonPropertiesFromJson
loadExpandoFields	Initializes the extended properties associated with the list item.
parseAndSetFieldValue	Sets the value of the field for the list item based on an implementation specific transformation of the value.
recycle	Moves the list item to the Recycle Bin and returns the identifier of the new Recycle Bin item.
refreshLoad	Reloads the extended properties associated with the list item.
update	Commits changed properties of the list item.
validateUpdateListItem	Validates and sets the values of the specified collection of fields for the list item.

Properties

The ListItem object has the following properties.

Property	Description
attachmentFiles	Specifies the collection of attachments that are associated with the list item.
contentType	Gets a value that specifies the content type of the list item.
displayName	Gets a value that specifies the display name of the list item.
effectiveBasePermissions	Gets a value that specifies the effective permissions on the list item that are assigned to the current user.
effectiveBasePermissionsForUI	Gets the effective base permissions for the current user, as they should be displayed in UI.
fieldValues	Gets a collection of key/value pairs containing the names and values for the fields of the list item.
fieldValuesAsHtml	Gets the values for the list item as HTML.
fieldValuesAsText	Gets the list item's field values as a collection of string values.
fieldValuesForEdit	Gets the formatted values to be displayed in an edit form.
file	Gets the file that is represented by the item from a document library.
fileSystemObjectType	Gets a value that specifies whether the list item is a file or a list folder.
folder	Gets a folder object that is associated with a folder item.
id	Gets a value that specifies the list item identifier.
item	Gets or sets the specified field value.
parentList	Gets the parent list that contains the list item.

Remarks

Contains CSOM expando fields, which correspond to the fields defined in the parent list. The CSOM expando field name is the name of the field defined in the list, and the CSOM expando field value is the field value in the list item. The following table defines the mapping between field types and values.

Field Type	CSOM Expando Field Value Type	Meaning
Integer	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Int32.	Allows an integer value.
Text	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Allows a limited-length string of text.
Note	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Allows larger amounts of text.
DateTime	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.	Allows full date and time values, as well as date-only values.
Counter	It must be CSOM Int32.	Allows a monotonically increasing integer field, which has a unique value in relation to other values that are stored for the field in the list. Counter is used only for the list item ID field, and not intended for use elsewhere.
Choice	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Allows selection from a set of suggested values. A choice field supports a field-level setting which specifies whether free-form values are supported.
Lookup	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Object.	Allows a reference to another list item. The field supports specification of a list identifier for a targeted list. An optional site ID can also be specified, which specifies the site of the list which contains the target of the lookup.
Boolean	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.	Allows a true or false value.
Number	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Double.	Allows a positive or negative number. A number field supports a field level setting used to specify the number of decimal places to display.
Currency	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Double.	Allows for currency-related data. The Currency field has a CurrencyLocaleId property which takes a locale identifier of the currency to use.
URL	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Object.	Allows a URL and optional description of the URL.
Computed	N/A	Renders output based on the value of other columns.
Threading	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Contains data on the threading of items in a discussion board.
Guid	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM GUID.	Specifies that the value of the field is a GUID.
MultiChoice	When its value is undefined; it must be CSOM null; otherwise, it must be CSOM Array.	Allows one or more values from a set of specified choices. A MultiChoice field can also support free-form values.
GridChoice	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Array.	Supports specification of multiple number scales in a list.
Calculated	N/A	Calculated based on the value of other columns.
File	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Specifies a reference to a file that can be used to retrieve the contents of that file.
Attachments	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.	Describes whether one or more files are associated with the item. true if a list item has attachments, and false if a list item does not have attachments.
User	When its value is undefined, it MUST be CSOM null; otherwise, it must be CSOM Object.	Contains a lookup to a particular user in the User Info list.
Recurrence	When its value is undefined, it MUST be CSOM null; otherwise, it must be CSOM Boolean.	Specifies whether a field contains a recurrence pattern for an item.
CrossProjectLink	When its value is undefined, it MUST be CSOM null; otherwise, it must be CSOM Boolean.	Allows a link to a Meeting Workspace site.
ModStat	When its value is undefined, it MUST be CSOM null; otherwise, it must be CSOM int32.	Specifies the current status of a moderation process on the document.
Error	N/A	Specifies errors. Value = 24.
ContentTypeId	When its value is undefined, it MUST be CSOM null; otherwise, it MUST be CSOM Object.	Contains a content type ID for an item. ContentTypeId conforms to the structure defined in ContentTypeId.
PageSeparator	N/A	Represents a placeholder for a page separator in a survey list. PageSeparator is only intended to be used with a Survey list.
ThreadIndex	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Contains a compiled index of threads in a discussion board.
WorkflowStatus	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Int32.	Contains status on a running workflow for a particular item.
AllDayEvent	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.	Used only in conjunction with an Events list. true if the item is an all-day event (that is, does not occur during a specific set of hours in a day).
WorkflowEventType	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Int32.	A description of a type of a historical workflow event. For more information, see WorkflowEventTypeEnumeration
Facilities	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Array.	Contains the facility or assets of the specified resource group.
FreeBusy	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Contains the free/busy information of the schedule.
Overbook	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Contains the double-booking information for the schedule.
Confidential	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.	Indicates whether this circulation can be viewed only by those to whom it was sent.
WhatsNew	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.	Indicates whether the current personal items are new in the group site.
DueDate	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.	Contains the date and time when the task is expected to be finished.
AllowEditing	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Boolean.	Indicates whether a user who is not the author can edit the content of this resource.
SendTo	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Array	Contains the users to whom this circulation was sent.
Confirmations	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Contains the confirmation information of this circulation.
CallTo	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM Array.	Contains the recipients who should track this note information.
CallTime	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.	Contains the date and time when this call was made.
Whereabout	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Contains the location of the user.
From	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.	Contains the date and time when Whereabouts status begins.
Until	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM DateTime.	Contains the date and time when the Whereabouts status ends.
ContactInfo	When its value is undefined, it must be CSOM null; otherwise, it must be CSOM String.	Contains the contact list of the user.

Example

The following example creates an input button on an application page that adds an item to the Announcements list on the current Web site.

<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
<script type="text/ecmascript" language="ecmascript">

    function runCode() {

        var clientContext = new SP.ClientContext();
        var targetList = clientContext.get_web().get_lists().getByTitle('Announcements');
        var itemCreateInfo = new SP.ListItemCreationInformation();

        this.newListItem = targetList.addItem(itemCreateInfo);

        newListItem.set_item('Title', 'MyNewAnnouncement');
        newListItem.set_item('Body', 'Hello World!');
        newListItem.update();
        clientContext.load(newListItem);

        clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
    }

    function onQuerySucceeded() {

        alert('Announcement created!\n\nId: ' + newListItem.get_id() + '\nTitle: ' + newListItem.get_item('Title'));
    }

    function onQueryFailed(sender, args) {

        alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
    }

</script>

    <input id="Button1" type="button" value="Run Code" onclick="runCode()" />

</asp:Content>

REST resource endpoint

See ListItem resource for more information.

Endpoint URI structure

http://<sitecollection>/<site>/_api/web/lists(listid)/items(itemid)

HTTP requests

This resource supports the following HTTP commands:

DELETE

DELETE syntax

DELETE http://<sitecollection>/<site>/_api/web/lists(listid)/items(itemid)

MERGE syntax

MERGE http://<sitecollection>/<site>/_api/web/lists(listid)/items(itemid)

POST syntax

POST http://<sitecollection>/<site>/_api/web/lists(listid)/items(itemid)