Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Customize a list view in SharePoint Add-ins using client-side rendering

SharePoint Add-ins

Learn how to customize a list view in a SharePoint-hosted app by using the client-side rendering technology in SharePoint 2013.

Last modified: June 04, 2015

Applies to: apps for SharePoint | Office 365 | SharePoint Add-ins | SharePoint Foundation 2013 | SharePoint Server 2013

Note Note

The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint". For details, see New name for apps for Office and SharePoint.

In SharePoint 2013, client-side rendering provides a way for you to produce your own output for a set of controls that are hosted in a SharePoint page. It enables you to use well-known technologies, such as HTML and JavaScript, to define the rendering logic of SharePoint list views. With client-side rendering, you can specify your own JavaScript resources and host them in the data storage options that are available to your apps, such as in a document library. A SharePoint-hosted app includes only SharePoint components. A SharePoint-hosted app has its resources in an isolated subsite of the host web, called the app web.

To follow the steps in this example, you will need the following:

  • Microsoft Visual Studio 2012

  • Office Developer Tools for Visual Studio 2012

  • A SharePoint 2013 development environment (app isolation required for on-premises scenarios)

For guidance on how to set up a development environment that fits your needs, see Start building apps for Office and SharePoint.

Core concepts to help you understand list view customization with client-side rendering

The following table lists useful articles that can help you understand the concepts that are involved in a list view customization scenario.

Table 1. Core concepts for list view customization in an app

Article title


SharePoint Add-ins

Learn about the new app model in Microsoft SharePoint 2013 that enables you to create apps, which are small, easy-to-use solutions for end users.

UX design for SharePoint Add-ins

Learn about the UX options that you have when you are building apps for SharePoint.

Host webs, app webs, and SharePoint components in SharePoint 2013

Learn about the difference between host webs and app webs. Find out which SharePoint 2013 components can be included in an app for SharePoint, which components are deployed to the host web, which components are deployed to the app web, and how the app web is deployed in an isolated domain.

To customize a list view that is deployed to the app web by using client-side rendering, follow these steps:

  1. Create the app for SharePoint project.

  2. Create a new list definition with a custom view.

  3. Provide the custom rendering logic in a JavaScript file.

Figure 1 shows a client-side rendered view of an announcements list.

Figure 1. Custom view of an announcements list

Custom view of an announcements list

To create the app for SharePoint project

  1. Open Visual Studio 2012 as administrator. (To do this, right-click the Visual Studio icon on the Start menu, and choose Run as administrator.)

  2. Create a new project using the App for SharePoint 2013 template.

    Figure 2 shows the location of the App for SharePoint 2013 template in Visual Studio 2012, under Templates, Visual C#, Office SharePoint, Apps.

    Figure 2. App for SharePoint 2013 Visual Studio template

    App for SharePoint 2013 Visual Studio template
  3. Provide the URL of the SharePoint website that you want to use for debugging.

  4. Select SharePoint-hosted as the hosting option for your app.

To create a new list definition

  1. Right-click the app for SharePoint project, and add a new List item. Create a customizable list based on Announcements.

  2. Copy the following markup and paste it in the Views element in the Schema.xml file of your list feature. The markup performs the following tasks:

    • Declares a new view named Overridable with a BaseViewID=2.

    • Provides a value for the JSLink element that points to a JavaScript file that is provisioned with the app.

    <View BaseViewID="2" 
        <FieldRef Name="Title" />
      <Query />
      <Toolbar Type="Standard" />
      <JSLink Default="TRUE">~site/Scripts/CSRListView.js</JSLink>

To provide the custom rendering logic in a JavaScript file

  1. Right-click the Scripts folder, and add a new JavaScript file. Name the file CSRListView.js.

  2. Copy the following code and paste it in the CSRListView.js file. The code performs the following tasks:

    • Provides event handlers for the PreRender and PostRender events.

    • Provides templates for the Header, Footer, and Item template sets.

    • Registers the templates.

    (function () {
        // Initialize the variable that stores the objects.
        var overrideCtx = {};
        overrideCtx.Templates = {};
        // Assign functions or plain html strings to the templateset objects:
        // header, footer and item.
        overrideCtx.Templates.Header = "<B><#=ctx.ListTitle#></B>" +
            "<hr><ul id='unorderedlist'>";
        // This template is assigned to the CustomItem function.
        overrideCtx.Templates.Item = customItem;
        overrideCtx.Templates.Footer = "</ul>";
        // Set the template to the:
        //  Custom list definition ID
        //  Base view ID
        overrideCtx.BaseViewID = 2;
        overrideCtx.ListTemplateType = 10057;
        // Assign a function to handle the
        // PreRender and PostRender events
        overrideCtx.OnPreRender = preRenderHandler;
        overrideCtx.OnPostRender = postRenderHandler;
        // Register the template overrides.
    // This function builds the output for the item template.
    // It uses the context object to access announcement data.
    function customItem(ctx) {
        // Build a listitem entry for every announcement in the list.
        var ret = "<li>" + ctx.CurrentItem.Title + "</li>";
        return ret;
    // The preRenderHandler attends the 
    OnPreRender event
    function preRenderHandler(ctx) {
        // Override the default title with user input.
        ctx.ListTitle = prompt("Type a title", ctx.ListTitle);
    // The postRenderHandler attends the 
    OnPostRender event
    function postRenderHandler(ctx) {
        // You can manipulate the DOM
     in the postRender event
        var ulObj;
        var i, j;
        ulObj = document.getElementById("unorderedlist");
        // Reverse order the list.
        for (i = 1; i < ulObj.children.length; i++) {
            var x = ulObj.children[i];
            for (j = 1; j < ulObj.children.length; j++) {
                var y = ulObj.children[j];
                    ulObj.insertBefore(y, x);

To build and run the solution

  1. Press the F5 key.

    Note Note

    When you press F5, Visual Studio builds the solution, deploys the app, and opens the permissions page for the app.

  2. Choose the Trust It button.

  3. Go to your custom List by entering the /Lists/<your_list_instance> address relative to your app directory in the app web domain (not the host web domain). Add one or two announcements. On the ribbon, choose the Overridable view.

This article demonstrated how to customize a list view in an app for SharePoint by using client-side rendering. As a next step, you can learn about the other UX components that are available for apps for SharePoint. To learn more, see the following:

© 2015 Microsoft