Skip to content

Commit f1a3673

Browse files
author
Pravandan Chand
committed
Add synchronous custom function conditional formatting sample
1 parent eb5db78 commit f1a3673

24 files changed

Lines changed: 825 additions & 1 deletion

‎.config/sample-config.json‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@
1010
],
1111
"technologies": [
1212
"Custom Functions",
13-
"Web Workers"
13+
"Web Workers",
14+
"Synchronous Custom Functions"
1415
]
1516
},
1617
"samples": [
@@ -127,6 +128,23 @@
127128
],
128129
"thumbnailPath": "assets/thumbnail.png",
129130
"suggested": false
131+
},
132+
{
133+
"id": "excel-custom-functions-sync-conditional-format",
134+
"onboardDate": "2026-03-19",
135+
"title": "Use synchronous custom functions with conditional formatting in Excel",
136+
"description": "Uses a synchronous custom function in a conditional format rule to highlight cells that exceed a target value.",
137+
"types": [
138+
"Excel"
139+
],
140+
"tags": [
141+
"TypeScript",
142+
"Custom Functions",
143+
"Excel",
144+
"Synchronous Custom Functions"
145+
],
146+
"thumbnailPath": "assets/thumbnail.png",
147+
"suggested": false
130148
}
131149
]
132150
}

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ The following samples show how to access and work with a user's Microsoft Graph
9292
| [Custom function batching pattern](Excel-custom-functions/Batching) | Batch multiple calls into a single call to reduce the number of network calls to a remote service. |
9393
| [Excel content add-in](Samples/excel-content-add-in) | Embed a content add-in in the Excel grid. |
9494
| [Excel content add-in with data visualization](Samples/excel-content-data-visualization) | Create an Excel content add-in that includes data visualization. |
95+
| [Synchronous custom function - conditional formatting](Samples/excel-custom-functions-sync-conditional-format) | Uses a synchronous custom function in a conditional format rule to highlight cells that exceed a target value. |
9596

9697
## Word
9798

‎Samples/excel-custom-functions-sync-conditional-format/.eslintrc.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"plugins": [
3+
"office-addins"
4+
],
5+
"extends": [
6+
"plugin:office-addins/recommended"
7+
]
8+
}

‎Samples/excel-custom-functions-sync-conditional-format/.gitignore‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
lerna-debug.log*
8+
9+
# Diagnostic reports (https://nodejs.org/api/report.html)
10+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
11+
12+
# Runtime data
13+
pids
14+
*.pid
15+
*.seed
16+
*.pid.lock
17+
18+
# Directory for instrumented libs generated by jscoverage/JSCover
19+
lib-cov
20+
21+
# Coverage directory used by tools like istanbul
22+
coverage
23+
*.lcov
24+
25+
# nyc test coverage
26+
.nyc_output
27+
28+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
29+
.grunt
30+
31+
# Bower dependency directory (https://bower.io/)
32+
bower_components
33+
34+
# node-waf configuration
35+
.lock-wscript
36+
37+
# Compiled binary addons (https://nodejs.org/api/addons.html)
38+
build/Release
39+
40+
# Dependency directories
41+
node_modules/
42+
jspm_packages/
43+
44+
# TypeScript v1 declaration files
45+
typings/
46+
47+
# TypeScript cache
48+
*.tsbuildinfo
49+
50+
# Optional npm cache directory
51+
.npm
52+
53+
# Optional eslint cache
54+
.eslintcache
55+
56+
# Microbundle cache
57+
.rpt2_cache/
58+
.rts2_cache_cjs/
59+
.rts2_cache_es/
60+
.rts2_cache_umd/
61+
62+
# Optional REPL history
63+
.node_repl_history
64+
65+
# Output of 'npm pack'
66+
*.tgz
67+
68+
# Yarn Integrity file
69+
.yarn-integrity
70+
71+
# dotenv environment variables file
72+
.env
73+
.env.test
74+
75+
# parcel-bundler cache (https://parceljs.org/)
76+
.cache
77+
78+
# Next.js build output
79+
.next
80+
81+
# Nuxt.js build / generate output
82+
.nuxt
83+
dist
84+
85+
# Gatsby files
86+
.cache/
87+
# Comment in the public line in if your project uses Gatsby and *not* Next.js
88+
# https://nextjs.org/blog/next-9-1#public-directory-support
89+
# public
90+
91+
# environment
92+
.env
93+
# vuepress build output
94+
.vuepress/dist
95+
96+
# Serverless directories
97+
.serverless/
98+
99+
# FuseBox cache
100+
.fusebox/
101+
102+
# DynamoDB Local files
103+
.dynamodb/
104+
105+
# TernJS port file
106+
.tern-port
107+
108+
localhost_manifest.xml
109+
test.rest
110+
personal.env
111+
personal_manifest.xml

‎Samples/excel-custom-functions-sync-conditional-format/README.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
page_type: sample
3+
urlFragment: excel-custom-functions-sync-conditional-format
4+
products:
5+
- office-excel
6+
- office
7+
languages:
8+
- typescript
9+
extensions:
10+
contentType: samples
11+
technologies:
12+
- Add-ins
13+
createdDate: 03/19/2026 4:00:00 PM
14+
description: "Shows how to use a synchronous custom function in a conditional format rule to highlight cells that exceed a target value."
15+
---
16+
17+
# Use Synchronous Custom Functions with Conditional Formatting in Excel
18+
19+
<img src="./assets/thumbnail.png" width="800" alt="A workbook with conditional formatting powered by a synchronous custom function.">
20+
21+
This sample shows how to use a synchronous custom function inside a conditional format rule to highlight cells dynamically. You'll learn how to:
22+
23+
- Create synchronous custom functions in Excel
24+
- Apply conditional format rules that use custom functions
25+
26+
## How to run this sample
27+
28+
### Prerequisites
29+
30+
- Download and install [Visual Studio Code](https://visualstudio.microsoft.com/downloads/).
31+
- Install the latest version of the [Office Add-ins Development Kit](https://marketplace.visualstudio.com/items?itemName=msoffice.microsoft-office-add-in-debugger) into Visual Studio Code.
32+
- Node.js (the latest LTS version). Visit the [Node.js site](https://nodejs.org/) to download and install the right version for your operating system. To verify if you've already installed these tools, run the commands `node -v` and `npm -v` in your terminal.
33+
- Microsoft Office connected to a Microsoft 365 subscription. You might qualify for a Microsoft 365 E5 developer subscription through the [Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program), see [FAQ](https://learn.microsoft.com/office/developer-program/microsoft-365-developer-program-faq#who-qualifies-for-a-microsoft-365-e5-developer-subscription-) for details. Alternatively, you can [sign up for a 1-month free trial](https://www.microsoft.com/microsoft-365/try?rtc=1) or [purchase a Microsoft 365 plan](https://www.microsoft.com/microsoft-365/buy/compare-all-microsoft-365-products).
34+
35+
### Run the add-in from the Office Add-ins Development Kit
36+
37+
1. Create a new project with the sample code.
38+
39+
Open the Office Add-ins Development Kit extension and view samples in the **Sample gallery**. Select the **Create** button in the top-right corner of the sample page. The new project will open in a second Visual Studio Code window. Close the original VSC window.
40+
41+
1. Open the Office Add-ins Development Kit.
42+
43+
Select the <img src="./assets/Icon_Office_Add-ins_Development_Kit.png" width="30" alt="The Office Add-ins Development Kit icon in the activity bar of VSCode"/> icon in the **Activity Bar** to open the extension.
44+
45+
1. Preview Your Office Add-in (F5).
46+
47+
Select **Preview Your Office Add-in(F5)** to launch the add-in and debug the code. In the drop down menu, select the option **Desktop (Edge Chromium)**.
48+
49+
<img src="./assets/devkit_preview.png" width="500" alt="The 'Preview your Office Add-in' option in the Office Add-ins Development Kit's task pane."/>
50+
51+
The extension checks that the prerequisites are met before debugging starts. The terminal will alert you to any issues with your environment. After this process, the Excel desktop application launches and opens a new workbook with the sample add-in sideloaded. The add-in automatically opens as well.
52+
53+
If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts. The first run requires installing dependency of this project, which might take 2~3 minutes or longer. During this time, there might be a dialog pop up at the lower right of the VSC screen. You should not interact with this dialog before the Office application launched.
54+
55+
1. Stop Previewing Your Office Add-in.
56+
57+
Once you are finished testing and debugging the add-in, select the <img src="./assets/Icon_Office_Add-ins_Development_Kit.png" width="30" alt="The Office Add-ins Development Kit icon in the activity bar of VSCode"/> icon and then select **Stop Previewing Your Office Add-in**. This closes the web server and removes the add-in from the registry and cache.
58+
59+
### Run the add-in locally
60+
61+
1. Open a terminal in the `Samples/excel-custom-functions-sync-conditional-format` folder.
62+
2. Run `npm install`.
63+
3. Run `npm start`.
64+
65+
## Use the sample add-in
66+
67+
1. Select the **Set up data and format** button in the task pane.
68+
2. The add-in populates cell A1 with "Target", A2 with the target value (70), and B1:B8 with a header and sample scores.
69+
3. A conditional format rule is applied to B2:B8 using the formula `=B2>SyncCFConditionalFormat.GETCELLVALUE("$A$2")`.
70+
4. Scores that exceed the target in A2 are highlighted in red.
71+
5. Change the value in A2 to see the conditional format highlights update live.
72+
73+
> **Note:** Synchronous custom functions are currently in public preview and require the beta Office JavaScript API. Do not use in production add-ins.
74+
75+
## Explore sample files
76+
77+
These are the important files in the sample project.
78+
79+
```
80+
| .eslintrc.json
81+
| .gitignore
82+
| .vscode/
83+
| | extensions.json
84+
| | launch.json Launch and debug configurations
85+
| | settings.json
86+
| | tasks.json
87+
| assets/ Static assets, such as images
88+
| babel.config.json
89+
| manifest*.xml Manifest file
90+
| package.json
91+
| README.md
92+
| RUN_WITH_EXTENSION.md
93+
| src/ Add-ins source code
94+
| | taskpane/
95+
| | | taskpane.html Task pane entry HTML
96+
| | | taskpane.js Add API calls and logic here
97+
| | functions/
98+
| | | functions.ts Custom function TypeScript
99+
| tsconfig.json
100+
| webpack.config.js Webpack config
101+
```
102+
103+
## Details
104+
105+
### Create the synchronous custom function
106+
107+
The `getCellValue` function in [functions.ts](src/functions/functions.ts) is marked with `@supportSync` so that it evaluates during Excel's calculation cycle. It creates a new `Excel.RequestContext`, calls `setInvocation` with the invocation parameter, and reads a cell value. For more details see the `getCellValue` function in [functions.ts](src/functions/functions.ts).
108+
109+
### Set up data and apply the conditional format rule
110+
111+
The [taskpane.js](src/taskpane/taskpane.js) file:
112+
113+
1. Populates sample data with a target threshold in A2 and scores in B2:B8.
114+
1. Adds a conditional format rule on B2:B8 using the formula `=B2>SyncCFConditionalFormat.GETCELLVALUE("$A$2")`.
115+
1. Highlights scores that exceed the target with a red fill.
116+
117+
When you change the value in A2, the conditional format updates live because the synchronous custom function re-evaluates during Excel's calculation.
118+
119+
## Troubleshooting
120+
121+
If you have problems running the sample, take the following steps.
122+
123+
- Close any open instances of Excel.
124+
- Close the previous web server started for the sample with the **Stop Previewing Your Office Add-in** Office Add-ins Development Kit extension option.
125+
- Try to run the sample again.
126+
127+
If you still have problems, see [troubleshoot development errors](https://learn.microsoft.com//office/dev/add-ins/testing/troubleshoot-development-errors) or [create a GitHub issue](https://aka.ms/officedevkitnewissue) and we'll help you.
128+
129+
For information on running the sample on Excel on the web, see [Sideload Office Add-ins to Office on the web](https://learn.microsoft.com/office/dev/add-ins/testing/sideload-office-add-ins-for-testing).
130+
131+
For information on debugging on older versions of Office, see [Debug add-ins using developer tools in Microsoft Edge Legacy](https://learn.microsoft.com/office/dev/add-ins/testing/debug-add-ins-using-devtools-edge-legacy).
132+
133+
## Make code changes
134+
135+
Once you understand the sample, make it your own! All the information about Office Add-ins is found in our [official documentation](https://learn.microsoft.com/office/dev/add-ins/overview/office-add-ins). You can also explore more samples in the Office Add-ins Development Kit. Select **View Samples** to see more samples of real-world scenarios.
136+
137+
If you edit the manifest as part of your changes, use the **Validate Manifest File** option in the Office Add-ins Development Kit. This shows you any errors in the manifest syntax.
138+
139+
## Engage with the team
140+
141+
Did you experience any problems with the sample? [Create an issue](https://github.com/OfficeDev/Office-Add-in-samples/issues/new/choose) and we'll help you out.
142+
143+
Want to learn more about new features and best practices for the Office platform? [Join the Microsoft Office Add-ins community call](https://learn.microsoft.com/office/dev/add-ins/overview/office-add-ins-community-call).
144+
145+
## Copyright
146+
147+
Copyright (c) 2026 Microsoft Corporation. All rights reserved.
148+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
149+
150+
<img src="https://pnptelemetry.azurewebsites.net/pnp-officeaddins/samples/excel-custom-functions-sync-conditional-format" />

‎Samples/excel-custom-functions-sync-conditional-format/RUN_WITH_EXTENSION.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Run the add-in from the Office Add-ins Development Kit
2+
3+
1. Open the Office Add-ins Development Kit.
4+
5+
Select the <img src="./assets/Icon_Office_Add-ins_Development_Kit.png" width="30" alt="Office Add-ins Development Kit"/> icon in the **Activity Bar** to open the extension.
6+
7+
1. Preview Your Office Add-in (F5).
8+
9+
Select **Preview Your Office Add-in(F5)** to launch the add-in and debug the code. In the drop down menu, select the option **Desktop (Edge Chromium)**.
10+
11+
<img src="./assets/devkit_preview.png" width="500" alt="The 'Preview your Office Add-in' option in the Office Add-ins Development Kit's task pane."/>
12+
13+
The extension checks that the prerequisites are met before debugging starts. The terminal will alert you to any issues with your environment. After this process, the Excel desktop application launches and opens a new workbook with the sample add-in sideloaded. The add-in automatically opens as well.
14+
15+
If this is the first time that you have sideloaded an Office Add-in on your computer (or the first time in over a month), you may be prompted to delete an old certificate and/or to install a new one. Agree to both prompts. The first run requires installing dependency of this project, which might take 2~3 minutes or longer. During this time, there might be a dialog pop up at the lower right of the VSC screen. You should not interact with this dialog before the Office application launched.
16+
17+
1. Stop Previewing Your Office Add-in.
18+
19+
Once you are finished testing and debugging the add-in, select the <img src="./assets/Icon_Office_Add-ins_Development_Kit.png" width="30" alt="The Office Add-ins Development Kit icon in the activity bar of VSCode"/> icon and then select **Stop Previewing Your Office Add-in**. This closes the web server and removes the add-in from the registry and cache.
20+
21+
22+
## Explore the add-in code
23+
24+
To explore an Office add-in project, you can start with the key files listed below.
25+
26+
- The `./manifest.xml` file in the root directory of the project defines the settings and capabilities of the add-in. <br>You can check whether your manifest file is valid by selecting **Validate Manifest File** option from the Office Add-ins Development Kit.
27+
- The `./src/functions/functions.ts` file contains the synchronous custom function TypeScript code.
28+
- The `./src/taskpane/taskpane.html` file contains the HTML markup for the task pane.
29+
- The `./src/taskpane/taskpane.js` file contains the Office JavaScript API code that sets up sample data and applies the conditional format rule.
30+
31+
## Troubleshooting
32+
33+
If you have problems running the sample, take these steps.
34+
35+
- Close any open instances of Excel.
36+
- Close the previous web server started for the sample with the **Stop Previewing Your Office Add-in** Office Add-ins Development Kit extension option.
37+
38+
If you still have problems, see [troubleshoot development errors](https://learn.microsoft.com//office/dev/add-ins/testing/troubleshoot-development-errors) or [create a GitHub issue](https://aka.ms/officedevkitnewissue) and we'll help you.
39+
40+
For information on running the sample on Excel on the web, see [Sideload Office Add-ins to Office on the web](https://learn.microsoft.com/office/dev/add-ins/testing/sideload-office-add-ins-for-testing).
41+
42+
For information on debugging on older versions of Office, see [Debug add-ins using developer tools in Microsoft Edge Legacy](https://learn.microsoft.com/office/dev/add-ins/testing/debug-add-ins-using-devtools-edge-legacy).
43+
44+
## See also
45+
46+
Once you understand the sample, make it your own! All the information about Office Add-ins is found in our [official documentation](https://learn.microsoft.com/office/dev/add-ins/overview/office-add-ins). You can also explore more samples in the Office Add-ins Development Kit. Select **View Samples** to see more samples of real-world scenarios.
47+
48+
Did you experience any problems with the sample? [Create an issue](https://github.com/OfficeDev/Office-Add-in-samples/issues/new/choose) and we'll help you out.
49+
50+
Want to learn more about new features and best practices for the Office platform? [Join the Microsoft Office Add-ins community call](https://learn.microsoft.com/office/dev/add-ins/overview/office-add-ins-community-call).

‎Samples/excel-custom-functions-sync-conditional-format/assets/Icon_Office_Add-ins_Development_Kit.png‎

592 Bytes
Loading

‎Samples/excel-custom-functions-sync-conditional-format/assets/devkit_preview.png‎

344 KB
Loading

‎Samples/excel-custom-functions-sync-conditional-format/assets/icon-128.png‎

4.58 KB
Loading

‎Samples/excel-custom-functions-sync-conditional-format/assets/icon-16.png‎

1.56 KB
Loading

0 commit comments

Comments
 (0)