Karine Bosch’s Blog

On SharePoint

ListFieldIterator Control

This control renders each field in a list item with an appropriate control. A single line text field will be rendered as a text box while a lookup field will be rendered as combo box. This control resides in the Microsoft.SharePoint.WebControls namespace of the Microsoft.SharePoint.dll.

You  can use this control in a custom application page or in a custom Edit, New and Display form.

In its simplest way you can declare the control as follows:

<spuc:ListFieldIterator ID="TestListFieldIterator" runat="server"
                        ControlMode="Edit" ListId="{e2886b6e-4d63-4063-a02c-eac7fb3aef79}" />

This renders the first list item as follows:


You can also set the ControlMode attribut to Display which renders the list item as follows:


If the control mode is set to New, empty controls are shown.

The way a choice field is rendered depends on the definition of the column. If you opted for a dropdown list when you created the column, the field is rendered as a dropdown. If you opted for check boxes for multi selection, the field is rendered as a list of check boxes:


If you defined a custom list definition depending on a custom content type with custom New, Edit and/or Display form, the ListFieldIterator control takes into account the values of the ShowInNewForm, ShowInEditForm and ShowInDisplayForm attributes. These attributes can be set while defining a site column in CAML using the <Field> element, or while defining a content type in CAML using the <FieldRef> element.

You can set different properties of the ListFieldIterator control:

  • ListId: This property must contain the id – which is a Guid – of the list you want to display.
  • ControlMode: Defines whether the controls are displayed in display mode, edit mode or new mode.
  • ExcludeFields: Specify the fields that don’t need to be rendered. Separate each field with ;#
  • Item: In code behind, you can retrieve the current list item by using this property.
  • ItemId: in code behind, you can retrieve the id of the current list item. But you can also decide which item to render by setting this attribute declaratively.
      <spuc:ListFieldIterator ID="TestListFieldIterator" runat="server"
            ControlMode="Edit" ListId="{e2886b6e-4d63-4063-a02c-eac7fb3aef79}" ItemId="2" />
  • List: In code behind, you can retrieve the current list by using this property.
  • Template: you can set this property if you have deployed your own custom template to the 12\TEMPLATE\CONTROLTEMPLATES folder.

If you first add one or more controls to render fields from the list, and then add a ListFieldIterator control, it will automatically detect the fields already rendered and will not render them anymore. This can be useful if you want to change the order in which the controls must appear, or even more if you want to change the standard rendering of one or more fields (f.e. if you want to render one of the fields using Silverlight 🙂 ).

<spuc:RichTextField ID="ContactTextField" runat="server"  
      ControlMode="Edit" ListId="{e2886b6e-4d63-4063-a02c-eac7fb3aef79}" FieldName="Description"/>
<spuc:ListFieldIterator ID="TestListFieldIterator" runat="server"
      ControlMode="Edit" ListId="{e2886b6e-4d63-4063-a02c-eac7fb3aef79}" />


This does not count for controls added AFTER the ListFieldIterator control.

Don’t forget to add a page directive in order to be able to use the control:

<%@ Register TagPrefix="spuc" Namespace="Microsoft.SharePoint.WebControls"
             Assembly="Microsoft.SharePoint, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

You can use this control in web parts and application pages but in general it is used in custom list definitions. When creating a custom list definition, the columns of the list will be rendered in a standard DisplayForm, NewForm and EditForm. If this standard rendering behavior does not satisfy your needs you can develop your own custom control templates. They need to be deployed in the 12\TEMPLATE\CONTROLTEMPLATES directory and need to be referenced in Forms element of the schema.xml of the custom list definition:

    <Form Type="DisplayForm" Url="DispForm.aspx" SetupPath="pages\form.aspx"  WebPartZoneID="Main"/>
    <Form Type="EditForm" Url="EditForm.aspx" SetupPath="pages\form.aspx" Template="CustomersForm" WebPartZoneID="Main"/>
    <Form Type="NewForm" Url="NewForm.aspx" SetupPath="pages\form.aspx" Template="CustomersForm" WebPartZoneID="Main"/>

The Template attribute must contain the name of the template that is defined in an ascx control deployed in the 12\TEMPLATE\CONTROLTEMPLATES folder.


  1. Excellent info – added a link to this post in the Community Content at http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.webcontrols.listfielditerator.aspx

    The MSDN documentation for SP is deeply flawed but if the community contributed by posting Community Content it would get a lot better, and would effectively demonstrate to MS what sections required additional info.

    Comment by Oskar Austegard | July 6, 2009 | Reply

  2. Karine, Excellent post, though I have one doubt, could you please explain how can I render attachment field using ListFieldIterator (as it seems attachment field is missing in your post)
    Also please explain, how can I get the value of particular field (Let’s suppose ‘Country’ field value) so that after submitting the form I want to display as… so and so country record has been updated…

    Thanks for your efforts, keep the good going 🙂

    Comment by VK | July 13, 2009 | Reply

    • VK, Not sure if you have managed to render attachments in your custom forms that use ListFieldIterator control but the following workaround could be helpful.

      To be simple, I only include the markup in the main content place holder:


      var elm = document.getElementById(“idAttachmentsTable”);
      if (elm == null || elm.rows.length == 0)
      document.getElementById(“idAttachmentsRow”).style.display = ‘none’;

      Comment by Vu Le | October 22, 2010 | Reply

    • Somehow the markup was not fully shown. Just reposted it.

      <span id=”part1″>
      <table width=”100%” cellpadding=”0″ cellspacing=”0″ border=”0″>
      <table class=”ms-formtoolbar” cellpadding=”2″ cellspacing=”0″ border=”0″ width=”100%”>
      <td width=”99%” class=”ms-toolbar” nowrap=””><img src=”/_layouts/images/blank.gif” width=”1″ height=”18″/></td>
      <td class=”ms-toolbar” nowrap=””>
      <SharePoint:SaveButton runat=”server” ControlMode=”New” id=”savebutton1″ ListId=”{…}”/>
      <td class=”ms-separator”> </td>
      <td class=”ms-toolbar” nowrap=”” align=”right”>
      <SharePoint:GoBackButton runat=”server” ControlMode=”New” id=”gobackbutton1″ ListId=”{…}”/>
      <SharePoint:FormToolBar ID=”FormToolBar1″ runat=”server” ControlMode=”New” ListId=”{…}”/>
      <table class=”ms-formtable” style=”margin-top: 8px;” border=”0″ cellpadding=”0″ cellspacing=”0″ width=100%> <SharePoint:ListFieldIterator ID=”ListFieldIterator1″ runat=”server” ControlMode=”New” />
      <tr id=”idAttachmentsRow”>
      <td width=”190px” valign=”top” class=”ms-formlabel” nowrap=”true”>
      <SharePoint:FieldLabel runat=”server” ID=”AttachmentsLabel” ControlMode=”New” FieldName=”Attachments” ListId=”{…}”/>
      <td width=”400px” valign=”top” class=”ms-formbody”>
      <SharePoint:FormField runat=”server” ID=”AttachmentsField” ControlMode=”New” FieldName=”Attachments” ListId=”{…}”/>
      <script type=”text/javascript”>
      var elm = document.getElementById(“idAttachmentsTable”);
      if (elm == null || elm.rows.length == 0)
      document.getElementById(“idAttachmentsRow”).style.display = ‘none’;
      <td colspan=”2″ class=”ms-formline”><img src=”/_layouts/images/blank.gif” width=”1″ height=”1″ alt=””/></td>
      <table class=”ms-formtoolbar” cellpadding=”2″ cellspacing=”0″ border=”0″ width=”100%” style=”margin-top: 7px;”>
      <td width=”99%” class=”ms-toolbar” nowrap=””><img src=”/_layouts/images/blank.gif” width=”1″ height=”18″/></td>
      <td class=”ms-toolbar” nowrap=””>
      <SharePoint:SaveButton runat=”server” ControlMode=”New” id=”savebutton2″ ListId=”{…}”/>
      <td class=”ms-separator”> </td>
      <td class=”ms-toolbar” nowrap=”” align=”right”>
      <SharePoint:GoBackButton runat=”server” ControlMode=”New” id=”gobackbutton2″ ListId=”{…}”/>
      <SharePoint:AttachmentUpload ID=”AttachmentUpload1″ runat=”server” ControlMode=”New” ListId=”{…}”/>
      <SharePoint:ItemHiddenVersion ID=”ItemHiddenVersion1″ runat=”server” ControlMode=”New” ListId=”{…}”/>

      Comment by Vu Le | October 22, 2010 | Reply

  3. […] Karine Bosch: ListFieldIterator Control […]

    Pingback by The ListFieldIterator webcontrol « Trungpv's Blog | February 11, 2010 | Reply

  4. Hi Karine,

    Thank you so much for such a nice article.

    I am using ListFieldIterator Control for one of my list. actully with this list, there are two content types are attached. So ListFieldIterator control just render the fields from default content type only. is it possible that i can set some property of ListFieldIterator contol and tell it to which content type’s field it has to render.

    any suggestion will be great help to me.


    Comment by Hemen | July 23, 2010 | Reply

  5. Hi Emen,
    The ListFieldIterator doesn’t have a property to set the content type. If you place the ListFieldIterator on a New or Edit form, you can pass the content type id in the URL: http://yourserver/page.aspx?ContentTypeId=0x010031DA61DB927BE4438D437FCA42E9231E

    When saving the page, you have to add following code to the submit button:
    listFieldIterator.Web.AllowUnsafeUpdates = true;
    // the next two lines were the missing pieces
    string ctypeID = this.Page.Request.QueryString[“ContentTypeId”];
    listFieldIterator.ListItem[“ContentTypeId”] = ctypeID;
    listFieldIterator.Web.AllowUnsafeUpdates = false;

    (This comes from a post of Peter Holpar (http://social.msdn.microsoft.com/Forums/en-US/sharepointdevelopment/thread/133c5707-e551-4fd9-af12-b17b1e1a2a43)


    Comment by Karine Bosch | July 24, 2010 | Reply

  6. Thanks a Lot Karine…Its working…

    I really appreciate your help..

    Comment by Hemen | July 27, 2010 | Reply

  7. Karine, thanks very much for lighting up this dark corner of Sharepoint.

    I’m looking for a way to arrange the values of a choice field (like Skills in the above example) four- or five-across, but I’m unsure as to what I’d need to do in order to achieve this. So if you can shed that much more light, I’d very much appreciate that.


    Comment by Josh | July 27, 2010 | Reply

  8. Hi Josh, what do you mean by arrange the values? Next to each other? Sorted?

    Anyway, if you want something different than the standard behavior, then you will have a to place a separate InputFormCheckBoxList control before using the ListFieldIterator. The ListFieldIterator will notice that the Skills field is already displayed and will not repeat it.


    Comment by Karine Bosch | July 28, 2010 | Reply

    • Karine, by “arrange the values”, I basically meant “next to each other”,e.g.

      [ ] First [ ] Second [ ] Third [ ] Fourth
      [ ] Fifth [ ] Sixth [ ] Seventh [ ] Eighth

      (the choice column in question has 30+ possible values).

      Is there any way I can get the ListFieldIterator to do something like this (and somehow control the number of elements between line breaks, or do I need to write something from scratch?

      Thanks, Josh

      Comment by Josh | July 28, 2010 | Reply

  9. You can use the InputFormCheckBoxList control and set its RepeatDirection property to Horizontal. Place the ListFIeldIterator control after the InputFormCheckBoxList control to make sure the choice field is not repeated, or set its ExcludeFields property to the choice field.

    info on the InputFormCheckBoxList control on my blog: (https://karinebosch.wordpress.com/sharepoint-controls/inputformcheckbox-inputformcheckboxlist-and-inputformcheckboxlistvalidator/)

    Hope this helps.

    Comment by Karine Bosch | July 28, 2010 | Reply

  10. Hi Karine,

    This is great piece of information. I created a content type with a custom edit form template (….). I want to make fields optional, required and also I want to change the drop down options in a lookup fields based on data entered or selected from previous fields, basically cascading based on certain conditions. Please advise me how this can be achieved. I truly appreciate your help.

    Comment by Manohar | September 11, 2010 | Reply

  11. Hi Karine

    This is an excellent post. I’ve a requirement where I need to make fields required, optional, change the items show in the drop down based on certain business rules. Can this be achieved using ListFieldIterator? What is the best way to tackle this problem? Appreciate your time and any help.


    Comment by Manohar | September 11, 2010 | Reply

  12. Hi Manohar,
    You can add code behind to you custom form template. In that code behind you can then add functionality to show/hide controls based on certain criteria.

    1. You add code in a separate class. This code contains the extra needed functionality

    2. At the top of your custom edit form, you add an Assembly directive where you references the assembly where you deployed your code:

    3. Within your custom edit form within the Template tag you add some inline code that instantiates the class and call upon the functionality:

    I’ll try to make a separate post on this later on this week.


    Comment by Karine Bosch | September 13, 2010 | Reply

  13. mmm, my code seems to be disappeared. You can write me a mail to karinebosch at hotmail dot com and I’ll send you some sample code.

    Comment by Karine Bosch | September 13, 2010 | Reply

  14. Hi Karine!

    Thanks for the post… it saved a lot of time. The control worked perfectly when I used it in a layout page.
    Now I encountered a problem when I used it in a custom webpart.
    I created my own webpart that adds a user control that holds the tag. Two things didn’t work:
    1. The output looks aweful. It’s not styled at all. It’s just plain text in displaymode and just Textboxes in editmode.
    2. When I set the ListId and ItemId in the Request (?List={something}&ID=3), or in the tag <spuc:ListFieldIterator ListId=… it just works fine. But when I set it in the code behind it will render the values of the list item. I tried the Items.Update and List.Update… didn't work either.

    Any ideas?

    Thanks in advance.

    Comment by Philipp | September 17, 2010 | Reply

  15. HI Karine
    I like your posts very very much.good work.

    Comment by venu | December 8, 2010 | Reply

    • can any one help to get the values from listfielditerator

      Comment by suri | January 6, 2011 | Reply

  16. After much fighting I have this thing working pretty well, the one exception being I can’t really figure out how to save the values set in this (while it’s in edit mode). I can see in the ViewState where the values are set for the individual controls but I would very much prefer not to have to go through the controls and try to match them up to the ListItem’s fields. It seems that the list item that is contained in the control doesn’t have the changed values (or at least not with the way I’m doing using this control via dynamically adding the control to the page). Is there some easy way to just tell it to save it’s values? Perhaps I’m missing something, maybe I should be trying to send it the Item Id and such in the query string? Is that really the only way?

    Comment by Mark | February 2, 2011 | Reply

  17. PS just tried the query string idea and I still can’t seem to see the changed values (IE if I have a field called Title and I change the value from Test to Test2 and click a save button in the postback I look at the field values/properties and it still shows Test. I can’t seem to find any other way to just make this thing save changed values.

    Comment by Mark | February 2, 2011 | Reply

  18. Ok nevermind….long day I was updating the wrong item.

    Comment by Mark | February 2, 2011 | Reply

  19. Hi Karine,

    Excellent post!!!
    I have a scenario, where I want to use control for people picker control instead of control rendered by ListField Iterator.

    Is there a way to specify the FielName property to the people editor control on my custom list form, so that it automatically saves to the list field from people editor control.
    I am working with a custom list definitions and list forms from visual studio. I want to handle some events on the people editor control in custom code, hence I want to use people editor instead of FormField. On form submit people editor control value has to be saved to the form field.

    Any suggestions on getting this.

    Many Thanks,

    Comment by mswin | July 4, 2011 | Reply

  20. Hi mswin,
    I think the control UserField could solve your problem.
    Kind regards,

    Comment by Karine Bosch | July 9, 2011 | Reply

  21. Hi Karine,
    I need to read from querystring of newform and store them in hidden fields of the same list. Is it possible? I am looking for your help Thx -S

    Comment by s | October 26, 2011 | Reply

  22. Excelent Post! Even after 2 years!

    Comment by Marcelo | July 18, 2012 | Reply

  23. Even in 2013 very useful to me. Thx.

    Comment by Volker Roth (@Shabbazz) | April 14, 2013 | Reply

  24. Hi,
    I have an asp drop down list in a WebPart, i bind All document library content types to this drop down list.
    when i choose a content type i need to display the fields of these content type to create new item from it

    how i can use ListFieldIterator or DocumentLibraryFields in this scenario
    please note that the i will add this webpart to an empty page.
    is that any property to set the content type of ListFieldIterator (or DocumentLibraryFields) and reload it to display the fields of content type ?

    Thank you in advance.

    Comment by hassan | January 3, 2015 | Reply

  25. Hi Karine,

    I have a problem with ListFieldIterator.
    When Im using it it display only text “FieldValue for “FieldName”” instead of real values.

    Any suggestions?
    Many Thanks,

    Comment by Tomasz | June 21, 2015 | Reply

  26. Hi Tomasz,
    how did you use the list field iterator ?

    Comment by Patrick | June 29, 2015 | Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: