Customize Modern SharePoint List Forms using JSON

We usually use SPFx or Power Apps to customize the forms in SharePoint online. This article will show how you can customize an out-of-box SharePoint list form using JSON. You don't need to customize the form using SPFx or Power Apps. Some simple JSON can be used to customize the header, footer, and body of the SharePoint list form. You can create different sections inside the form body and apply some validations to show and hide form fields based on the value of other form fields. The advantage of these JSON customized forms is that they are responsive by default. You don't have to do any work to make these forms responsive. So, you can use the same form in desktop and mobile.

Create a custom list

Create a custom list using the template 'Work progress tracker'. I have used this template for my example. You can use any other template or create your own custom list based on the requirement.

When you click on the 'New' button of the list, this is out of the box new/ edit form for the list. There is no customization. All fields are visible, as shown in below image.

For our example, we will create a new column, 'Manager' for the manager of the assigned user. We will show this field only if a work item is 'Critical' in priority.

Show/Hide form field based on conditions

We have a requirement to show the Manager field in the form only when Priority is Critical. To apply a conditional check to show/hide the Manager field, click the New list button to open the list form. Click on Edit columns from top right options available in New form.

Select the Edit conditional formula for the Manager field in the context menu of the field.

You will see below a blank screen to add your formula for the field.

To learn more about conditional formula, please click on the link below to see how to do it: https://learn.microsoft.com/en-us/sharepoint/dev/declarative-customization/list-form-conditional-show-hide#specify-conditional-formula-to-show-or-hide-columns

Formulas are equations that perform conditional checks on column values in a list or library. A formula starts with an equal sign (=) followed by the if the function that returns either a true or a false result.

For example, the following formula checks if the value for the Priority column is Critical:

=if([$Priority] == 'Critical', 'true', 'false')

Returning true results in showing the column on the form, while returning false hides the column.

Below is our custom formula based on our requirement to show/ hide the Manager field.

Once you add your formula for the field, your field will be greyed out. This indicates that this field has some custom formula applied to it.

We need to save these changes to apply this formula to the field. Click on the Save button to save the changes.

Reorder fields on the form

We can reorder columns fields of the form. Here we will shift Manager near the Assigned to field. Whatever field you want to move, drag and drop the field to your desired location. To save the changes, click on the Save button.

Test the changes

Now you have reordered the form fields and applied conditions to show/ hide the Manager field based on the selected Priority. Let's test this by creating a new item in the list and selecting different priorities.

As you can see in the image above, the Manager field is visible when Priority is Critical.

When you change Priority from Critical to anything else, the Manager field is not visible. In the above image, we have selected Priority as High. So, the Manager field is not visible.

Add sections to form body

Now we want to arrange form fields in different sections like Work item details, Status details, and Assignment details. We can do this with the help of JSON without doing any customizations.

To add sections to the SharePoint list form, click the New button to open the form and select the Configure layout option from the options in the top right corner, as shown in the image below.

You will see options like Header, Body, and Footer in the Format window. You need to select Body.

You must add your JSON in the Formatting code field in this window. If you need to learn more about JSON custom formatting, check Learn more link for examples of JSON: https://learn.microsoft.com/en-us/sharepoint/dev/declarative-customization/list-form-configuration

Copy the example from the link and modify it according to your requirements:

For our example, JSON will be like this. Here we are adding 3 sections to the form: work item details, Status details, and Assignment details. We have specified fields also inside each of these sections. You need to specify the field display name for each field inside the section to regroup this fields inside sections.

{
    "sections": [
        {
            "displayname": "Work item details",
            "fields": [
                "Work item",
                "Description",
                "Category",
               "Priority"
            ]
        },
        {
            "displayname": "Status details",
            "fields": [
                "Progress",
                "Start date",
                "Due date",
                "Notes"
            ]
        },
        {
            "displayname": "Assignment details",
            "fields": [
                "Assigned to",
                "Manager"
            ]
        },
        {
            "displayname": "",
            "fields": []
        }
    ]
}

Click the Save button to save these changes and regroup fields of the form in different sections. After saving these changes, you will see the changes when you click on the New button to open a new form.

As you can see in the image, all three sections are separated with horizontal line and have section headers. If you see JSON, we have one empty section in the last. This section holds all those fields not included in any of the above sections. Here blank section has the Attachments field.

Now if you edit form columns from the top right option available in New form, you can see all the fields grouped in different sections. You can also reorder or move these fields from this screen.

Customize Form Header using JSON

In the New form Configure layout, select Header in the Format window as shown in the below image.

You can use Learn more link in this window and check for the Header section. Here is the link for Header customization: https://learn.microsoft.com/en-us/sharepoint/dev/declarative-customization/list-form-configuration#configure-custom-header

You can copy the code provided in this link and change it as required. You can change text and icon etc., which is visible in the header of the form.

For icons, you can use any Fluent UI Icons from this link: https://developer.microsoft.com/en-us/fluentui#/styles/web/icons

For my example, I select the WorkiIem icon, as shown in the image below.

Final JSON code for my example:

{
    "elmType": "div",
    "attributes": {
        "class": "ms-borderColor-neutralTertiary"
    },
    "style": {
        "width": "99%",
        "border-top-width": "0px",
        "border-bottom-width": "1px",
        "border-left-width": "0px",
        "border-right-width": "0px",
        "border-style": "solid",
        "margin-bottom": "16px"
    },
    "children": [
        {
            "elmType": "div",
            "style": {
                "display": "flex",
                "box-sizing": "border-box",
                "align-items": "center"
            },
            "children": [
                {
                    "elmType": "div",
                    "attributes": {
                        "iconName": "WorkItem",
                        "class": "ms-fontSize-42 ms-fontWeight-regular ms-fontColor-themePrimary",
                        "title": "Details"
                    },
                    "style": {
                        "flex": "none",
                        "padding": "0px",
                        "padding-left": "0px",
                        "height": "36px"
                    }
                }
            ]
        },
        {
            "elmType": "div",
            "attributes": {
                "class": "ms-fontColor-neutralSecondary ms-fontWeight-bold ms-fontSize-24"
            },
            "style": {
                "box-sizing": "border-box",
                "width": "100%",
                "text-align": "left",
                "padding": "21px 12px",
                "overflow": "hidden"
            },
            "children": [
                {
                    "elmType": "div",
                    "txtContent": "='Work progress for ' + [$Title]"
                }
            ]
        }
    ]
}

After adding JSON, when you try to edit any item, the header will be visible as in the below image. This has the Icon we changed for WorkItem and has our custom text with the value of the Work item field (which is the Title field internally). We have to use the internal name of fields in JSON.

Customize Form Footer using JSON

In the New form Configure layout, select Footer in the Format window as shown in the below image.

You can use Learn more link in this window and check for the Footer section. Here is the link for Footer customization:  https://learn.microsoft.com/en-us/sharepoint/dev/declarative-customization/list-form-configuration#configure-custom-footer

You can copy the code provided in this link and change it as required.

JSON for the footer:

{
    "elmType": "div",
    "style": {
        "width": "100%",
        "text-align": "left",
        "overflow": "hidden",
        "border-top-width": "1px"
    },
    "children": [
        {
            "elmType": "div",
            "style": {
                "width": "100%",
                "padding-top": "10px",
                "height": "24px"
            },
            "children": [
                {
                    "elmType": "a",
                    "txtContent": "='Contact Details for ' + [$Title]",
                    "attributes": {
                        "target": "_blank",
                        "href": "='https://aka.ms/contacts?email=' + [$CreatedBy]",
                        "class": "ms-fontColor-themePrimary ms-borderColor-themePrimary ms-fontWeight-semibold ms-fontSize-m ms-fontColor-neutralSecondary–hover ms-bgColor-themeLight–hover"
                    }
                }
            ]
        }
    ]
}

You can see the footer shown in the below image.

If you want to learn more about list form formatting using JSON, you can refer to learning links from Microsoft on this topic.

Show or hide columns in a list or library form: https://learn.microsoft.com/en-us/sharepoint/dev/declarative-customization/list-form-conditional-show-hide

Configure the list form: https://learn.microsoft.com/en-us/sharepoint/dev/declarative-customization/list-form-configuration