JSON Formatting in SharePoint: Transform Lists Without Code

JSON Formatting in SharePoint: Transform Lists Without Code

Introduction

JSON formatting lets you apply rich UI enhancements to SharePoint lists and libraries without deploying SPFx, custom scripts, or page layouts. Column formatting transforms individual fields (status badges, icons, conditional colors); view formatting reshapes entire list views (card layouts, grouped sections); row actions add inline buttons for navigation or workflows. All changes apply instantly, require no admin deployment, and remain portable across tenants.

This guide covers column formatting patterns, view formatting for card layouts, row action buttons, advanced conditionals, accessibility considerations, and a governance approach for reusable templates.

Prerequisites

• SharePoint Online list/library
• Permissions to modify list settings

Formatting Options Overview

Step-by-Step Guide

Step 1: Identify Business Scenario

Example scenarios:

• Visualize project status with color-coded badges (Red/Yellow/Green)
• Highlight overdue tasks with icons and warning colors
• Add "View Details" buttons that navigate to item display forms
• Display user profiles with persona cards
• Show progress bars for completion percentages
• Surface metadata as clickable pills (tags, categories)

Step 2: Column Formatting Example

Status badge with conditional color:

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "attributes": {
    "class": "=if(@currentField == 'Complete', 'sp-field-severity--good', if(@currentField == 'In Progress', 'sp-field-severity--warning', 'sp-field-severity--blocked'))"
  },
  "children": [
    { "elmType": "span", "txtContent": "@currentField" }
  ]
}

Icon + text for Priority field:

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "style": { "display": "flex", "align-items": "center" },
  "children": [
    {
      "elmType": "span",
      "attributes": {
        "iconName": "=if(@currentField == 'High', 'WarningSolid', 'Info')"
      },
      "style": { "padding-right": "8px", "color": "=if(@currentField == 'High', '#d13438', '#0078d4')" }
    },
    { "elmType": "span", "txtContent": "@currentField" }
  ]
}

### Step 3: View Formatting Example

**Card layout with title, due date, and status badge:**
```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/view-formatting.schema.json",
  "hideSelection": true,
  "rowFormatter": {
    "elmType": "div",
    "attributes": {
      "class": "ms-borderColor-neutralLight ms-borderWidth-1 ms-borderStyle-solid ms-rounded"
    },
    "style": {
      "padding": "16px",
      "margin-bottom": "8px",
      "box-shadow": "0 2px 4px rgba(0,0,0,0.1)"
    },
    "children": [
      {
        "elmType": "div",
        "style": { "display": "flex", "justify-content": "space-between", "margin-bottom": "8px" },
        "children": [
          { "elmType": "span", "txtContent": "@Title", "style": { "font-weight": "600", "font-size": "16px" } },
          { "elmType": "span", "txtContent": "[$DueDate]", "style": { "color": "#605e5c" } }
        ]
      },
      {
        "elmType": "div",
        "txtContent": "[$Status]",
        "attributes": {
          "class": "=if([$Status] == 'Complete', 'sp-field-severity--good', if([$Status] == 'In Progress', 'sp-field-severity--warning', 'sp-field-severity--blocked'))"
        }
      }
    ]
  }
}

### Step 4: Add Row Action Button

**Button to open item display form:**
```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "button",
  "txtContent": "View Details",
  "customRowAction": {
    "action": "defaultClick"
  },
  "style": {
    "background-color": "#0078d4",
    "color": "white",
    "border": "none",
    "padding": "6px 12px",
    "border-radius": "2px",
    "cursor": "pointer"
  }
}

External link button:

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "a",
  "txtContent": "Open Project",
  "attributes": {
    "href": "=[$ProjectUrl]",
    "target": "_blank",
    "class": "ms-fontColor-themePrimary ms-fontWeight-semibold"
  }
}

### Step 5: Governance & Reuse

**Centralize patterns:**
- Store approved JSON templates in a SharePoint document library or GitHub repo
- Version templates with semantic versions (v1.0, v1.1)
- Tag templates by use case (Status Badge, Card View, Action Button)

**Change management:**
- Require peer review for new patterns before broad adoption
- Document breaking changes (e.g., field name dependencies)
- Use Power Automate to notify owners when centralized patterns update

**Naming conventions:**
- Prefix internal field names consistently (`ctso_Status`, `ctso_Priority`)
- Reference fields with `[$FieldName]` syntax for clarity and future-proofing

### Step 6: Performance & Usability Review

**Accessibility:**
- Ensure color contrast ratios meet WCAG 2.1 AA (4.5:1 for text)
- Avoid relying solely on color; pair with icons or text labels
- Test with screen readers; use `aria-label` where needed

**Performance:**
- Limit nesting depth (3-4 levels max) to avoid rendering delays
- Simplify conditional expressions; avoid complex inline calculations
- Test with 100+ items to validate scroll performance

**Responsiveness:**
- Use flexible layouts (`display: flex`) for mobile/tablet views
- Test in SharePoint mobile app and mobile browser
- Avoid fixed widths; prefer `min-width` and `max-width`

## Best Practices

- **Keep Formatting Minimal:** Avoid over-styling; focus on clarity and actionable insights.
- **Use Conditional Logic for Clarity:** Highlight risk flags, overdue items, or status changes with color/icons.
- **Centralize Reusable Patterns:** Store templates in a shared library; version and document dependencies.
- **Reference Fields Consistently:** Use `[$FieldInternalName]` syntax; avoid hardcoding display names.
- **Test Accessibility:** Validate color contrast, screen reader compatibility, and keyboard navigation.
- **Validate JSON Before Apply:** Use online JSON validators or the SharePoint schema validator.
- **Avoid Heavy Computations:** Keep expressions simple; move complex logic to calculated columns or Power Automate.
- **Document Field Dependencies:** Clearly note which fields the formatting requires (e.g., Status, Priority, DueDate).






## Troubleshooting

**Issue:** Formatting not applied  
**Solution:** Validate JSON schema URL & syntax; ensure field internal names match; clear browser cache.





**Issue:** Slow list rendering  
**Solution:** Simplify nested elements; remove heavy conditional chains; reduce expression complexity.

**Issue:** Colors or styles not showing  
**Solution:** Check that class names (e.g., `sp-field-severity--good`) are valid; use inline `style` objects as fallback.

**Issue:** Buttons or links not clickable  
**Solution:** Verify `customRowAction` or `href` syntax; ensure no overlay elements block interaction.

**Issue:** Formatting breaks after column rename  
**Solution:** Update JSON to reference the new internal name; avoid using display names in expressions.

**Issue:** Mobile rendering issues  
**Solution:** Test with flexible layouts (`display: flex`); avoid fixed widths; validate in SharePoint mobile app.

## Architecture Decision and Tradeoffs

When designing content management and collaboration solutions with SharePoint, consider these key architectural trade-offs:

| Approach | Best For | Tradeoff |
|----------|----------|----------|
| Managed / platform service | Rapid delivery, reduced ops burden | Less customisation, potential vendor lock-in |
| Custom / self-hosted | Full control, advanced tuning | Higher operational overhead and cost |

> **Recommendation:** Start with the managed approach for most workloads and move to custom only when specific requirements demand it.

## Validation and Versioning

- Last validated: April 2026
- Validate examples against your tenant, region, and SKU constraints before production rollout.
- Keep module, CLI, and SDK versions pinned in automation pipelines and review quarterly.

## Security and Governance Considerations

- Apply least-privilege access using RBAC roles and just-in-time elevation for admin tasks.
- Store secrets in managed secret stores and avoid embedding credentials in scripts or source files.
- Enable audit logging, data protection policies, and periodic access reviews for regulated workloads.

## Cost and Performance Notes

- Define budgets and alerts, then monitor usage and cost trends continuously after go-live.
- Baseline performance with synthetic and real-user checks before and after major changes.
- Scale resources with measured thresholds and revisit sizing after usage pattern changes.

## Official Microsoft References

- https://learn.microsoft.com/sharepoint/
- https://learn.microsoft.com/microsoft-365/enterprise/
- https://learn.microsoft.com/purview/

## Public Examples from Official Sources

- These examples are sourced from official public Microsoft documentation and sample repositories.
- Documentation examples: https://learn.microsoft.com/sharepoint/dev/
- Sample repositories: https://github.com/SharePoint/sp-dev-docs
- Prefer adapting these examples to your tenant, subscriptions, and governance requirements before production use.

## Key Takeaways

- **JSON Formatting Accelerates UX Improvements:** Apply rich UI enhancements without deploying custom code or SPFx.
- **Column and View Formatting Serve Different Purposes:** Column for field-level badges/icons; view for card layouts and grouped sections.
- **Governance Ensures Consistent, Maintainable Patterns:** Centralize templates, version them, and document field dependencies.
- **Accessibility and Performance Matter:** Validate color contrast, test responsiveness, and simplify expressions.





## Next Steps

- Audit top 5 lists for formatting opportunities (status indicators, overdue highlights, action buttons)
- Build an internal pattern catalog in a shared library with version tags and usage examples
- Pilot form formatting (preview feature) for custom headers and body layouts
- Integrate Power Automate to auto-apply formatting templates to new lists


## Additional Resources

- [Column Formatting](https://learn.microsoft.com/sharepoint/dev/declarative-formatting/column-formatting)
- [View Formatting](https://learn.microsoft.com/sharepoint/dev/declarative-formatting/view-formatting)
- [JSON Schema Reference](https://learn.microsoft.com/sharepoint/dev/declarative-formatting/json-schema)


---

*Which list will you modernize first?*