Microsoft Lists JSON Formatting: Complete Guide (2026)
Master column, view, and form formatting in Microsoft Lists with copy-paste JSON examples. 2,100+ PnP community samples included.
Why Does Microsoft Lists Formatting Matter in 2026?
With over 200 million monthly active SharePoint Online users (MedhaCloud, 2026), Microsoft Lists has become the default structured-data tool across enterprises. Yet most lists still look like plain spreadsheets — rows of text with no visual cues. JSON formatting fixes that without a single line of deployed code.
You don't need SPFx. You don't need Power Apps. You paste JSON into a formatting panel, hit save, and your list transforms into something your team actually wants to use — color-coded status badges, progress bars, conditional icons, and card-based views.
This guide covers all three formatting types (column, view, and form), gives you production-ready JSON you can copy today, and shows you where to find 2,100+ community samples when you need more.
Key Takeaways
- Microsoft Lists supports three JSON formatting types: column, view, and form — each targeting a different part of the UI
- The PnP List-Formatting repository contains 2,100+ community samples with 919 forks (GitHub, 2026)
- Column formatting requires zero deployment — paste JSON, save, done
- Copilot integration with Lists reached General Availability in January 2026 (HANDS ON Lists, 2026)
- SPFx Field Customizers were saved from retirement after community pushback — JSON formatting remains the recommended first approach
---
What Are the Three Types of Microsoft Lists Formatting?
Microsoft's formatting syntax reference documents 9 elmType values, 100+ CSS style properties, 40+ operators, and 8 customRowAction types (Microsoft Learn, 2025). That sounds overwhelming. It isn't — because all of it breaks down into three distinct scopes.
Column Formatting
Targets a single column. You change how one field renders — turn "In Progress" text into a blue pill badge, or show a percentage as a visual bar. Every other column stays untouched.
When to use it: Status indicators, progress bars, conditional icons, clickable action buttons on a single field.
View Formatting
Targets the entire row or switches the layout to cards, tiles, or a board. You control how rows render across all columns in a specific view — alternating row colors, highlighting overdue items, or building a Kanban-style board.
When to use it: Alternating row styles, row-level conditional highlighting, gallery/board views, grouped header formatting.
Form Formatting
Targets the new/edit/display form. You rearrange fields into sections, add headers and footers, hide fields conditionally, and control the form layout when users create or edit items.
When to use it: Multi-section forms, conditional field visibility, branded form headers, custom submit buttons.
---
How Do You Apply Column Formatting?
SharePoint processes over 500 trillion files and documents monthly (Jobera, 2025), and column formatting lets you customize how any of that data renders — without deploying a single package. Getting started takes four clicks. Here's the exact path.
- Open your Microsoft List (or SharePoint list)
- Click the column header you want to format
- Select Column settings → Format this column
- Click Advanced mode at the bottom of the panel
- Paste your JSON and click Save
That's it. The formatting applies instantly to every item in that column. Anyone with edit permissions on the list sees the change. Want to undo it? Delete the JSON and save — you're back to the default.
The JSON Structure
Every column formatting JSON starts with the same skeleton:
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
"elmType": "div",
"style": {
"display": "flex",
"align-items": "center"
},
"children": [
{
"elmType": "span",
"txtContent": "@currentField"
}
]
}The $schema property is optional but gives you IntelliSense in VS Code. The elmType defines what HTML element to render. The @currentField token pulls in the actual column value.
Our finding: After testing across multiple tenants, the $schema property doesn't affect rendering at all — it's purely for editor support. Skip it if you're pasting directly into the SharePoint panel, but always include it when storing formatting JSON in version control.---
What Are the Most Useful Column Formatting Examples?
The PnP List-Formatting repository tracks 1,920 commits of community-contributed samples (GitHub, 2026), and five patterns show up more than any others. Why? Because they cover 80% of what teams actually need. Each one below is copy-paste ready — just update the field values to match your column.
1. Status Badge with Conditional Colors
Turn a Choice column into colored pills. This is the single most requested formatting pattern.
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
"elmType": "div",
"style": {
"display": "flex",
"align-items": "center",
"justify-content": "center",
"border-radius": "16px",
"padding": "4px 12px",
"font-size": "12px",
"font-weight": "600",
"color": "white",
"background-color": "=if(@currentField == 'Completed', '#22c55e', if(@currentField == 'In Progress', '#f97316', if(@currentField == 'Not Started', '#64748b', '#38bdf8')))"
},
"txtContent": "@currentField"
}This maps "Completed" to green, "In Progress" to orange, "Not Started" to gray, and everything else to blue. Adjust the string comparisons to match your Choice column values.
2. Progress Bar from a Number Column
Show a percentage as a visual bar with the number overlaid.
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
"elmType": "div",
"style": {
"width": "100%",
"height": "24px",
"background-color": "#e2e8f0",
"border-radius": "12px",
"overflow": "hidden",
"position": "relative"
},
"children": [
{
"elmType": "div",
"style": {
"width": "=toString(@currentField) + '%'",
"height": "100%",
"background-color": "=if(@currentField >= 80, '#22c55e', if(@currentField >= 50, '#f97316', '#ef4444'))",
"border-radius": "12px",
"transition": "width 0.3s ease"
}
},
{
"elmType": "span",
"style": {
"position": "absolute",
"left": "50%",
"top": "50%",
"transform": "translate(-50%, -50%)",
"font-size": "11px",
"font-weight": "700",
"color": "#1e293b"
},
"txtContent": "=toString(@currentField) + '%'"
}
]
}Values 80+ show green. 50-79 shows orange. Below 50 is red. The bar width scales with the value automatically.
3. Due Date with Overdue Highlighting
Highlight dates that have passed in red, upcoming dates in yellow, and future dates normally.
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
"elmType": "div",
"style": {
"padding": "4px 8px",
"border-radius": "4px",
"background-color": "=if(@currentField <= @now, '#fecaca', if(@currentField <= @now + 259200000, '#fef3c7', 'transparent'))",
"color": "=if(@currentField <= @now, '#dc2626', if(@currentField <= @now + 259200000, '#d97706', 'inherit'))"
},
"txtContent": "@currentField"
}The magic number 259200000 is 3 days in milliseconds. Items due within 3 days get a yellow warning. Overdue items turn red. Everything else stays default.
4. Person Column with Profile Image
Show the user's profile picture alongside their name — makes lists feel more like a modern app.
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
"elmType": "div",
"style": {
"display": "flex",
"align-items": "center",
"gap": "8px"
},
"children": [
{
"elmType": "img",
"attributes": {
"src": "='/_layouts/15/userphoto.aspx?size=S&accountname=' + @currentField.email"
},
"style": {
"width": "28px",
"height": "28px",
"border-radius": "50%",
"object-fit": "cover"
}
},
{
"elmType": "span",
"txtContent": "@currentField.title"
}
]
}5. Clickable Action Button
What if your users could approve a request directly from the list view — no form, no Flow trigger, just one click? That's what action buttons do.
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
"elmType": "button",
"style": {
"background-color": "#f97316",
"color": "white",
"border": "none",
"border-radius": "6px",
"padding": "6px 14px",
"cursor": "pointer",
"font-size": "12px",
"font-weight": "600"
},
"txtContent": "Approve",
"customRowAction": {
"action": "setValue",
"actionInput": {
"Status": "Approved"
}
}
}This creates an "Approve" button that sets the Status column to "Approved" when clicked. No Power Automate required for simple status transitions.
According to the PnP community, their List-Formatting repository now holds over 2,100 stars and 919 forks with 1,920 commits of community-contributed JSON samples (GitHub, 2026). Before building from scratch, search that repo — someone has probably solved your exact use case already.
---
How Does View Formatting Work?
With 75% of organizations using SharePoint via Microsoft 365 integration (Jobera, 2025), view formatting is how most teams transform flat tables into visual dashboards. Column formatting targets one field. View formatting controls the entire row or transforms the layout altogether. You access it through List settings → Format current view → Advanced mode.
Ever built a Kanban board in Trello, then wished your SharePoint list looked the same? That's exactly what view formatting solves.
View formatting uses a different JSON schema:
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/view-formatting.schema.json",
"additionalRowClass": "=if([$DueDate] <= @now, 'sp-css-backgroundColor-errorBackground', '')"
}The additionalRowClass property adds CSS classes to entire rows conditionally. SharePoint provides built-in CSS classes you can reference — no custom stylesheets needed.
Alternating Row Colors
The simplest view formatting — make every other row slightly different for readability:
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/view-formatting.schema.json",
"additionalRowClass": "=if(@rowIndex % 2 == 0, 'sp-css-backgroundColor-neutralBackground', '')"
}Highlight Overdue Rows
Turn entire rows red when a date column has passed:
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/view-formatting.schema.json",
"additionalRowClass": "=if([$DueDate] <= @now, 'sp-css-backgroundColor-errorBackground sp-css-color-errorText', '')"
}Replace [$DueDate] with your actual column internal name. The [$ColumnName] syntax accesses any column in the row — that's the key difference from column formatting's @currentField.
Row Formatting with Custom HTML
For full control, use the rowFormatter property instead of additionalRowClass:
{
"$schema": "https://developer.microsoft.com/json-schemas/sp/v2/view-formatting.schema.json",
"rowFormatter": {
"elmType": "div",
"style": {
"display": "flex",
"align-items": "center",
"padding": "8px 16px",
"border-left": "=if([$Priority] == 'High', '4px solid #ef4444', if([$Priority] == 'Medium', '4px solid #f97316', '4px solid #22c55e'))",
"margin-bottom": "4px"
},
"children": [
{
"elmType": "span",
"style": { "font-weight": "600", "flex": "1" },
"txtContent": "[$Title]"
},
{
"elmType": "span",
"style": { "font-size": "12px", "opacity": "0.7" },
"txtContent": "[$AssignedTo.title]"
}
]
}
}This renders each row as a card with a colored left border based on priority. High = red, Medium = orange, Low = green.
When using rowFormatter, you take full control of the row HTML. SharePoint won't render the default column layout anymore — you must explicitly include every field you want visible.---
How Do You Format List Forms?
Microsoft Lists now offers 14 built-in templates with pre-configured forms (Microsoft Support, 2026), but form formatting lets you go further. It's the newest of the three types and the one most teams overlook. You can rearrange the new/edit/display form into sections, add a branded header, and hide fields based on conditions. Access it through List settings → Customize forms → Configure layout.
Have you ever watched users struggle with a 20-field form when they only need 5 of those fields at their current step? Conditional sections fix that.
Here's a form layout that groups fields into logical sections:
{
"sections": [
{
"displayname": "Request Details",
"fields": ["Title", "Description", "RequestType", "Priority"]
},
{
"displayname": "Assignment",
"fields": ["AssignedTo", "DueDate", "Status"]
},
{
"displayname": "Resolution",
"fields": ["Resolution", "CompletedDate"],
"isVisible": "=if([$Status] == 'Completed', 'true', 'false')"
}
]
}The "Resolution" section only appears when Status is "Completed." Your users don't see fields they don't need yet — the form adapts to the workflow stage.
Form Header and Footer
Add a branded header with context:
{
"headerJSONFormatter": {
"elmType": "div",
"style": {
"background-color": "#f97316",
"padding": "16px 20px",
"border-radius": "8px 8px 0 0",
"margin-bottom": "16px"
},
"children": [
{
"elmType": "span",
"style": { "color": "white", "font-size": "18px", "font-weight": "700" },
"txtContent": "New Support Request"
},
{
"elmType": "span",
"style": { "color": "white", "opacity": "0.8", "font-size": "13px", "display": "block", "margin-top": "4px" },
"txtContent": "='Submitted by: ' + @me"
}
]
},
"footerJSONFormatter": {
"elmType": "div",
"style": { "text-align": "center", "padding": "12px", "font-size": "12px", "opacity": "0.5" },
"txtContent": "Items are routed automatically based on Request Type"
}
}The @me token inserts the current user's name. Combined with conditional sections, you can build multi-step forms that rival Power Apps — without leaving the list.
---
What JSON Syntax Do You Need to Know?
Microsoft's formatting syntax reference documents 9 elmType values, 40+ operators, and 8 customRowAction types (Microsoft Learn, 2025). That's a lot to memorize. Here's the quick reference — bookmark this section and come back to it every time you write formatting JSON.
If you're comfortable with SharePoint column formatting basics, this reference table takes you to the next level.
Element Types (elmType)
Special Tokens
| Token | Returns | Example |
|---|---|---|
@currentField | Current column value | Status text, number, date |
@currentField.title | Person display name | "Jane Smith" |
@currentField.email | Person email | "jane@contoso.com" |
[$ColumnName] | Any column value (view/form) | [$DueDate], [$Priority] |
@me | Current user email | For conditional "my items" |
@now | Current timestamp | Date comparisons |
@rowIndex | Row position (0-based) | Alternating styles |
@thumbnail.medium | Document thumbnail URL | File preview images |
@window.innerWidth | Viewport width | Responsive formatting |
Operators
| Operator | Syntax | Example |
|---|---|---|
| Conditional | =if(condition, true, false) | =if(@currentField > 50, 'green', 'red') |
| Equals | == | =if(@currentField == 'Done', ...) |
| Not equals | != | =if([$Status] != 'Closed', ...) |
| Greater/Less | >, <, >=, <= | =if(@currentField >= 80, ...) |
| AND | && | =if(@currentField > 0 && @currentField < 100, ...) |
| OR | || | =if([$Status] == 'Done' || [$Status] == 'Closed', ...) |
| Ternary | Nested if | =if(a, x, if(b, y, z)) |
| String concat | + | =@currentField + ' items' |
| toString | toString() | =toString(@currentField) + '%' |
---
When Should You Use JSON Formatting vs. SPFx vs. Power Apps?
80% of Fortune 500 companies rely on SharePoint for document management (Jobera, 2025), and each team has to choose the right customization approach. This is the question that trips up most projects. Here's the decision framework I've used across enterprise tenants — it saves hours of building the wrong thing.
Already working with SPFx? Our SPFx hello world guide covers the development setup, and the PnP JS data guide shows how to fetch list data in web parts.
In 2025, Microsoft initially planned to retire SPFx Field Customizers, which would have made JSON formatting the only option for column-level customization. After significant community pushback, they reversed that decision — SPFx Field Customizers remain fully supported (HANDS ON Lists, 2025). But the reversal tells you something: Microsoft sees JSON formatting as the primary path for most use cases.
Choose JSON formatting when:
- You need visual changes only (colors, icons, layout)
- The logic is conditional but simple (if/else chains)
- You want zero deployment overhead
- Non-developers need to maintain it
Choose SPFx Field Customizers when:
- You need external API calls during render
- Complex business logic exceeds nested-if readability
- You need to render React components
- Custom event handling beyond built-in actions
Choose Power Apps when:
- You need multi-screen navigation
- The form requires complex validation logic
- External data sources must be combined
- You want offline-capable mobile forms
75% of organizations use SharePoint via Microsoft 365 integration (Jobera, 2025). For most of them, JSON formatting covers the customization needs without introducing development complexity. SPFx and Power Apps are there when you genuinely outgrow it — not before.
---
How Does Copilot Work with Formatted Lists?
Copilot integration with Microsoft Lists reached General Availability in January 2026 (HANDS ON Lists, 2026). The Knowledge Agent can read, filter, and summarize list data — and formatting affects how useful that interaction is.
Here's what matters: Copilot reads the underlying data, not your formatting JSON. But well-structured lists with clear column names and consistent Choice values give Copilot better context. A Status column with "Done", "In Progress", "Blocked" gives Copilot clean categories to work with. A Status column with "done", "Done!", "completed", "DONE" creates confusion.
Formatting Best Practices for Copilot Compatibility
- Use consistent Choice values — standardize before formatting. Your JSON conditions depend on exact string matches anyway.
- Name columns descriptively — "RequestPriority" beats "Col3". Copilot uses column names as context.
- Keep formatting JSON in version control — Copilot can't help you debug formatting if you lose track of what's applied where.
- Don't rely on visual-only information — if a red background means "overdue," make sure there's also a column value (like a calculated Overdue field) that Copilot can read.
Microsoft Lists now offers 14 built-in templates including 2026 additions like Remote Work Requests and ESG Tracking (Microsoft Support, 2026). These templates come pre-formatted — study their JSON to learn patterns you can adapt.
Want to go deeper on Copilot governance? Our Microsoft Copilot governance best practices guide covers the enterprise controls you'll need.
---
Where Do You Find Ready-Made Formatting Samples?
The PnP community has contributed 919 forks to the official List-Formatting repository (GitHub, 2026). Why reinvent the wheel? The community has been building formatting samples since Microsoft Lists launched, and the collection is massive.
PnP List-Formatting Repository
The official community repository at github.com/pnp/List-Formatting is the first place to check. With 2,100+ stars and 1,920 commits, it's actively maintained and covers everything from simple status badges to full Kanban boards.
Each sample includes:
- The JSON file, ready to copy
- A screenshot showing what it looks like
- A README explaining the setup
- The minimum SharePoint version required
Microsoft's Built-In Design Mode
Before diving into JSON, try the Design Mode panel. Click Format this column → Design mode and you get a point-and-click interface for basic conditional formatting. It generates the JSON for you. It won't handle complex layouts, but it's a solid starting point for simple status badges and date highlights.
VS Code with the SharePoint JSON Schema
Add the $schema property to your JSON (shown in every example above) and VS Code gives you autocomplete, validation, and inline documentation. You'll catch typos in property names before pasting into SharePoint.
---
What Changed in Microsoft Lists Formatting for 2025-2026?
Copilot integration with Microsoft Lists reached General Availability in January 2026 (HANDS ON Lists, 2026), marking the biggest shift in how lists work since the original launch. If you last looked at Lists formatting a year ago, several things have shifted. Still using the old mobile app? It's gone.
New in 2025-2026:
- Copilot Knowledge Agent integration (GA January 2026)
- Two new built-in templates: Remote Work Requests and ESG Tracking
- SPFx Field Customizer retirement reversed after community feedback
- Enhanced
@window.innerWidthtoken for responsive formatting
Deprecated or Removed:
- Microsoft Lists mobile apps retired November 15, 2025. The browser experience at office.com/launch/Lists continues, and formatting renders correctly there.
- Some older CSS class names in
sp-css-*namespace were consolidated
80% of Fortune 500 companies rely on SharePoint for document management (Jobera, 2025). Lists formatting gives those enterprises a way to modernize their interfaces without the overhead of custom development. If you're managing permissions for these formatted lists at scale, our SharePoint permissions guide covers the full permission model.
---
What Are the Most Common Formatting Mistakes?
With 446 million paid Microsoft 365 seats globally (MedhaCloud, 2026), a lot of people are writing formatting JSON — and making the same mistakes. After working with Lists formatting across multiple enterprise tenants, these are the issues I see most often. Each one has a quick fix. Sound familiar?
Mistake 1: Using Display Names Instead of Internal Names
In view and form formatting, you reference columns with [$ColumnName]. But "ColumnName" must be the internal name, not the display name. If you created a column called "Due Date" (with a space), the internal name is Due_x0020_Date.
Fix: Go to list settings, click the column name, and check the URL — the internal name appears in the Field= parameter.
Mistake 2: Forgetting String Comparison Is Case-Sensitive
=if(@currentField == 'done', ...) won't match "Done" or "DONE". JSON formatting comparisons are exact.
Fix: Either standardize your Choice values or use toLowerCase():
=if(toLowerCase(@currentField) == 'done', ...)Mistake 3: Nesting Too Many Conditionals
Five levels of nested if statements become unreadable and unmaintainable. I've seen formatting JSON files hit 200+ lines because of cascading conditions.
Fix: Use the indexOf + array pattern for many-to-one mappings. Or switch to SPFx if your logic needs that many branches — formatting JSON wasn't designed for complex business rules.
Mistake 4: Not Testing on Mobile
The Lists mobile apps were retired in November 2025, but users still access lists through the mobile browser. Have you tested your formatting on a phone? Formatting renders differently on small screens. Wide layouts break. Tiny text becomes unreadable.
Fix: Use @window.innerWidth to create responsive formatting:
"font-size": "=if(@window.innerWidth < 480, '14px', '12px')"---
Frequently Asked Questions
Does Microsoft Lists formatting require coding skills?
Not traditional coding, but you need basic JSON literacy. Microsoft's Design Mode generates JSON from point-and-click choices, covering simple conditional formatting without writing a line. For advanced layouts, you'll paste and modify JSON templates — the PnP repository's 2,100+ samples (GitHub, 2026) mean you're rarely starting from zero.
Can formatting break my list data?
No. Formatting is purely visual — it changes how data renders, not the data itself. Remove the formatting JSON and your list looks exactly like it did before. SharePoint processes over 500 trillion documents monthly (Jobera, 2025), and formatting doesn't alter a single byte of that data. It's the safest customization you can apply.
Does formatting work in Microsoft Teams?
Yes. When you embed a Microsoft List as a tab in Teams, column and view formatting render correctly. With 446 million paid Microsoft 365 seats (MedhaCloud, 2026), Teams is where most users interact with lists. Form formatting also works from within Teams. The formatting JSON lives with the list, not the host app, so it follows the list wherever it appears.
How many columns can I format in a single list?
There's no documented limit. Microsoft's syntax reference supports 9 elmType values and 100+ CSS properties per column (Microsoft Learn, 2025). I've seen lists with 15+ formatted columns running fine. However, extremely complex JSON on many columns simultaneously can cause slow rendering on older browsers. Keep individual column JSON under 50 lines for best performance.
Will Copilot eventually generate formatting JSON for me?
Microsoft hasn't announced this specific capability, but the direction is clear. Copilot reached GA for Microsoft Lists in January 2026 (HANDS ON Lists, 2026) focused on data interaction — filtering, summarizing, creating items. Formatting generation would be a natural next step given that the JSON schema is well-documented and deterministic.
---
Start Formatting Your Lists Today
Microsoft Lists JSON formatting is one of those rare features where the effort-to-impact ratio is wildly in your favor. A 10-line JSON snippet turns a boring text column into a visual status board. A 30-line view formatter transforms a flat table into something teams actually enjoy using.
Here's your action plan:
- Pick one list that your team uses daily
- Start with the status badge example from this guide — it takes 2 minutes
- Browse the PnP samples at github.com/pnp/List-Formatting for your next upgrade
- Store your JSON in version control — formatting applied through the UI has no undo history
- Graduate to view formatting once you're comfortable with columns
For the JSON syntax reference that powers all of this, check our SharePoint column formatting guide for additional basics, or explore the provisioning automation guide if you want to deploy formatting at scale across multiple lists.
The 200 million SharePoint users aren't going anywhere. Make their lists worth looking at.