Click here to Skip to main content
15,435,841 members
Articles / Productivity Apps and Services / Sharepoint / SharePoint 2013
Posted 28 Aug 2014


17 bookmarked

SharePoint 2013 Client Side Rendering: List Forms

Rate me:
Please Sign up or sign in to vote.
5.00/5 (10 votes)
28 Aug 2014CPOL8 min read
Client Side Rendering specifics related to list forms.


Client Side Rendering was introduced in SharePoint 2013 as a main technique for displaying data, replacing XSLT. CSR is now used by default for displaying data from standard lists (exceptions: Survey and Calendar lists) - including list forms, list views and lists in Quick Edit mode, - and search results.

Although CSR is reused for displaying all of those, the process for different data sources differs significantly. I explained CSR basics and specifics of CSR for list views in the previous article: SharePoint 2013 Client Side Rendering: List Views. In this article, I'll focus on list forms: how they work, what are the gotchas, and how to use them. This article contains 4 code examples:

  • Primitive example: customizing how field value is displayed
  • Primitive example: customizing field control
  • Example: dependent fields
  • Example: manipulating form layout

CSR for List Forms

List forms in SharePoint 2013 can be rendered using one of 3 modes: Standard, Custom and Server Render:

Image 1.

Server Render falls back to XSLT, while Standard and Custom are based on CSR.

Standard Mode

When in Standard mode, ListFormWebPart renders a template for the form, including the table structure and even field captions. As a placeholder for field values or controls, ListFormWebPart renders empty span elements with unique identifiers, like this:

Image 2

During the page load, a reduced CSR process is launched over and over again for every field in the form, and after each field is rendered, the corresponding span element will be replaced with the generated by CSR process HTML.

The rendering of the form is handled by method RenderForm. Reduced CSR process and replacing the span contents for a given field is performed by method RenderReplace:

Image 3

I call CSR in Standard mode reduced, because not all the stages are processed. View, Header, Footer, Body and Group handlers never get executed. Thus it's not possible to change layout of the fields by means of CSR templates. The only way to change the form layout in this mode is to rearrange the already rendered DOM elements e.g. by using jQuery.

Obviously, Standard mode is mostly used to customize rendering of field controls/values.

Primitive Example: Customizing How Field Value is Displayed

The following code customizes, how field value is displayed on a Display form:


  Templates: {

    Fields: {
      'Title': {
        DisplayForm: function(ctx) {
          return '<div class="my-field-title">' + ctx.CurrentItem.Title + '</div>';




Image 4


Comparing to list views CSR, list forms CSR process is a bit more complicated, because in addition to displaying, list forms should provide edit capability. It is obvious that in order to perform editing of a value, you have to interact with CSR core, at least providing it with the value that was entered into your custom control.

This is done with the help of ctx.FormContext.updateControlValue(fieldName, value) function. The ctx.FormContext object also contains a lot of other useful information for rendering forms and processing their values.

Another useful function of ctx.FormContext is registerInitCallback(fieldName, callback). It's convenient to use it instead of PostRender, though essentially it does same thing: executes the provided callback right after field is created.

ctx.FormContext is an instance of the ClientFormContext class. Below is the full definition of this class:

class ClientFormContext {
    fieldValue: any;
    fieldSchema: SPClientTemplates.FieldSchema_InForm;
    fieldName: string;
    controlMode: number;
    webAttributes: {
        AllowScriptableWebParts: boolean;
        CurrentUserId: number;
        EffectivePresenceEnabled: boolean;
        LCID: string;
        PermissionCustomizePages: boolean;
        WebUrl: string;
    itemAttributes: {
        ExternalListItem: boolean;
        FsObjType: number;
        Id: number;
        Url: string;
    listAttributes: {
        BaseType: number;
        DefaultItemOpen: number;
        Direction: string;
        EnableVesioning: boolean;
        Id: string;
    registerInitCallback(fieldname: string, callback: () => void ): void;
    registerFocusCallback(fieldname: string, callback: () => void ): void;
    registerValidationErrorCallback(fieldname: string, callback: (error: any) => void ): void;
    registerGetValueCallback(fieldname: string, callback: () => any): void;
    updateControlValue(fieldname: string, value: any): void;
    registerClientValidator(fieldname: string,
    validator: SPClientForms.ClientValidation.ValidatorSet): void;
    registerHasValueChangedCallback(fieldname: string, callback: (eventArg?: any) => void );

This definition was taken from open source project TypeScript Definitions for SharePoint 2013. Using this project and TypeScript, you can get intellisense and type checking for your CSR code. TypeScript then compiles into JS.

Primitive Example: Customizing a Field Control

This is the code:

function MyFieldControl(ctx) {

  // Instead of hardcoding the field value, we can fetch it from the context
  var fieldInternalName = ctx.CurrentFieldSchema.Name;
  var controlId = fieldInternalName + "_control";

  // Initialization of the field: here I'm attaching onchange event to my control,
  // so that whenever text is changed, FormContext.updateControlValue is executed.
  ctx.FormContext.registerInitCallback(fieldInternalName, function () {

      $addHandler($get(controlId), "change", function(e) {
          ctx.FormContext.updateControlValue(fieldInternalName, $get(controlId).value);


  return String.format('<input type="text"
  id="{0}" name="{0}" class="my-input" />', controlId);

  Templates: {
     Fields: {
       'Title': {
         EditForm: MyFieldControl,
         NewForm: MyFieldControl


$get and $addHandler functions come from ASP.NET Ajax library, as well as String.format. This library is deployed to every SharePoint page by default. If you want, you can get rid of these functions and replace them with either jQuery or pure JS or whatever else you like.

Now this code will work and it is about as simplified as possible. However, it is recommended to add two more calls into the MyFieldControl template handler: registerFocusCallback and registerValidationErrorCallback. This will ensure consistent behavior of your custom field. So here's the final version of the handler:

function MyFieldControl(ctx) {

    var fieldInternalName = ctx.CurrentFieldSchema.Name;
    var controlId = fieldInternalName + "_control";

    ctx.FormContext.registerInitCallback(fieldInternalName, function () {
        $addHandler($get(controlId), "change", function(e) {
            ctx.FormContext.updateControlValue(fieldInternalName, $get(controlId).value);

    ctx.FormContext.registerFocusCallback(fieldInternalName, function() {

    ctx.FormContext.registerValidationErrorCallback(fieldInternalName, function(errorResult) {
        SPFormControl_AppendValidationErrorMessage(controlId, errorResult);

    return String.format('<input type="text" id="{0}" 
    name="{0}" class="my-input" />', controlId);

So far so good. But how about something more interesting and something more real-world? What if we need interaction between fields, so that when you change one field, another field changes correspondingly?

Example: Dependent Fields

Dependant fields tend to be one of the most wanted features for SharePoint list forms. Now with CSR, we finally got a very good way of implementing them using solely OOTB features.

Consider you have cars, and each car can be of a different color. Every time you select a car, you then should check which colors are currently available for the selected car, and hide colors that aren't relevant.

Something like this:

Image 5

Probably the simplest way to do it is to use OnPostRender event. In that case, you don't need to redefine anything - and so you end up with less code; but on the other hand, you have to know how OOTB fields are rendered so that you could manipulate them after render.

So I opened developer tools window in Internet Explorer and quickly found the id of the select control that I can track:

Image 6

Obviously here field ID, field type and field name are composed into the control ID. All this information is available from the context object, so in terms of code it looks like this:

var f = ctx.ListSchema.Field[0];
var fieldControlId = f.Name + "_" + f.Id + 
"_$" + f.FieldType + "Field";

Notice I'm using Field[0], that's because rendering in Standard mode processes one field at a time (as explained above), and so there is always only one field in ctx.ListSchema when OnPostRender event fires.

Once we got the HTML control, we can subscribe to its onchange event, and every time a change happens, we can then e.g. perform some async event and then based on the received response decide, which colors we should hide.

But how do you hide the radio buttons?

One more time into the developer tools window. Here it is:Image 7

So basically, the same structure here. But now the fact that there is only one field in the context plays against me: I don't want to hardcore the field Id, because it is ugly! :) So what can I do?

After some digging, I found that the original ListSchema is stored in global variable window[ctx.FormUniqueId + "FormCtx"].ListSchema. Nice, the problem is solved now:

var colorFieldName = "Color";
var colorField = window[ctx.FormUniqueId + "FormCtx"].ListSchema[colorFieldName];
var colorFieldControlId = colorField.Name + "_" + 
colorField.Id + "_$" + colorField.FieldType + "Field" + colorId;

Where colorId is 0 = Black, 1 = White, 2 = Green, etc.

So we have the initial control, subscribed to onchange event, received some data from external list, got the color field controls, and the only thing left is to disable them and that is easy. So here's the final code!


    Templates: {
      OnPostRender: function(ctx){
        var colorField = window[ctx.FormUniqueId + "FormCtx"].ListSchema["Color"];
        var colorFieldControlId = colorField.Name + "_" + 
        colorField.Id + "_$RadioButton" + colorField.FieldType + "Field";
        var f = ctx.ListSchema.Field[0];
        if (f.Name == "Car")
          var fieldControl = $get(f.Name + "_" + 
          f.Id + "_$" + f.FieldType + "Field");
          $addHandler(fieldControl, "change", function(e)
              // first, let's hide all the colors - while the information is loading
              for (var i = 0;i<5;i++)
                $get(colorFieldControlId + i) = "none";
              var newValue = fieldControl.value;
              var newText = fieldControl[fieldControl.selectedIndex].text;
              var context = SP.ClientContext.get_current();
              // here add logic for fetching information from an external list
              // based on newText and newValue
                  // fill this array according to the results of the async request
                  var showColors = [];
                  if (newText == "Kia Soul") showColors = [0, 2, 3];
                  if (newText == "Fiat 500L") showColors = [1, 4];
                  if (newText == "BMW X5") showColors = [0, 1, 2, 3, 4];

                  // now, display the relevant ones
                  for (var i = 0;i<showColors.length;i++)
                    $get(colorFieldControlId + showColors[i])"";
              function(sender, args)
                alert("Error! " + args.get_message());

        } else if (f.Name == "Color") {
          // initialization: hiding all the choices. first user must select a car
          for (var i = 0;i<5;i++)
            $get(colorFieldControlId + i) = "none";


And the result:

Image 8

Example: Manipulating Form Layout

Sometimes, it is necessary to add some additional UI, create sections, or otherwise change the layout of the form. In Standard mode, with the reduced CSR process, layout cannot be simply overridden, as in list views. But it is still possible to do some layout manipulation, and here I demonstrate one method of doing so...

In this example, I will insert an extra row after a certain field in the table.

As I already mentioned, ListFormWebPart renders special span elements that later get replaced during the CSR process. These span elements have simple ids, so we can manipulate them easily. We should do it in OnPreRender callback, so that the span is still there and not yet replaced with the field content.

Once we took hold of a span element that is related to a certain field, it is easy to e.g. insert something below or above this element. In the following example, I'm inserting an additional row into the form. Obviously, you can put any HTML there, and thus create any kind of extra UI. For example, it can be a map, and by clicking on it user might pre-fill the form values...

So here's the code, it's pretty simple:

    OnPreRender: function(ctx) {
      var fieldName = ctx.ListSchema.Field[0].Name;
      if (fieldName == "Title")
          var span = $get(ctx.FormUniqueId + ctx.FormContext.listAttributes.Id + fieldName);
          var tr = document.createElement('tr');
 = "#ada";
          tr.innerHTML="<td colspan='2'>&nbsp;</td>";
          var fieldTr = span.parentNode.parentNode;
          fieldTr.parentNode.insertBefore(tr, fieldTr.nextSibling);


Image 9

Custom Mode

The custom mode should have been the full-scale CSR mode, where both layout, field captions and field controls are generated with CSR.

Unfortunately, based on my investigation, it seems unlikely that Custom mode was really even tested, because the bugs are very obvious and everywhere :(

So here is what happens if you just switch a list form to Custom mode, via Web Part Properties:

Image 10

Amazing, isn't it? :)

I performed some investigations and after about 3 days of struggle, I ended up with some sort of work around. But I had to write a lot of wrapping code and even after all the efforts, the solution was not perfect and I had to perform additional manipulations via OnPreRender method in order to fix a minor problem; and also I even had to render the field labels manually...

Overall, I wouldn't recommend switching to Custom mode at all.


CSR for list forms is a great way of solving most common tasks related to list form customizations. It is far from perfect, but it is probably the best way to do it, and also it is the recommended and the supported way. So I would definitely stick to CSR when planning form customizations.

Unfortunately, the mode that is supposed to address layout customizations, doesn't quite work at the time of writing, so the only satisfactory way to do the layout changes now - is to use DOM manipulations, that can be relatively slow in case of big number of fields.

So good luck with your forms!

Update 16.10.2015: After the CustomLayout mode issue was not fixed even in SP2016 IT Preview, I came up with 50 lines of code that solve the layout problem, enabling fully CSR-compatible custom templates. Have a look:

Also, check out another article I wrote a while ago about using CSR together with KnockoutJs:


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Written By
Finland Finland
Full stack developer, enterprise web software. Microsoft MVP, open source person, speaker, online expert.

Comments and Discussions

QuestionUnexpected Render Pin
CA Simon25-Nov-19 5:39
MemberCA Simon25-Nov-19 5:39 
QuestionQuick Edit Using CSR Pin
Member 127436599-Apr-18 3:25
MemberMember 127436599-Apr-18 3:25 
QuestionMany Tanks Pin
Member 806305724-Nov-16 4:06
MemberMember 806305724-Nov-16 4:06 
AnswerRe: Many Tanks Pin
Andrei Markeev24-Nov-16 4:35
MemberAndrei Markeev24-Nov-16 4:35 
GeneralRe: Many Tanks Pin
Member 806305724-Nov-16 6:03
MemberMember 806305724-Nov-16 6:03 
QuestionExample: Dependent Fields Pin
Member 1239632616-Mar-16 5:02
MemberMember 1239632616-Mar-16 5:02 
AnswerRe: Example: Dependent Fields Pin
Andrei Markeev2-Dec-16 12:10
MemberAndrei Markeev2-Dec-16 12:10 
QuestionCSR for event/calendar lists Pin
Mihail-Florin Popa29-Sep-15 0:59
MemberMihail-Florin Popa29-Sep-15 0:59 
AnswerRe: CSR for event/calendar lists Pin
Andrei Markeev29-Sep-15 22:11
MemberAndrei Markeev29-Sep-15 22:11 
GeneralRe: CSR for event/calendar lists Pin
Mihail-Florin Popa30-Sep-15 3:53
MemberMihail-Florin Popa30-Sep-15 3:53 
GeneralRe: CSR for event/calendar lists Pin
Andrei Markeev30-Sep-15 5:20
MemberAndrei Markeev30-Sep-15 5:20 
GeneralRe: CSR for event/calendar lists Pin
Mihail-Florin Popa30-Sep-15 8:52
MemberMihail-Florin Popa30-Sep-15 8:52 
GeneralRe: CSR for event/calendar lists Pin
Andrei Markeev30-Sep-15 9:48
MemberAndrei Markeev30-Sep-15 9:48 
GeneralRe: CSR for event/calendar lists Pin
Mihail-Florin Popa16-Oct-15 1:50
MemberMihail-Florin Popa16-Oct-15 1:50 
GeneralRe: CSR for event/calendar lists Pin
Andrei Markeev16-Oct-15 2:04
MemberAndrei Markeev16-Oct-15 2:04 
QuestionRefresh row with jslink Pin
sidali9220-Sep-15 22:07
Membersidali9220-Sep-15 22:07 
AnswerRe: Refresh row with jslink Pin
Andrei Markeev21-Sep-15 0:38
MemberAndrei Markeev21-Sep-15 0:38 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.