name: ui-extensions
description: This skill should be used when the user asks to "build a Todoist extension", "create a UI extension", "design a Doist Card", "add a context menu or composer surface", "set up a bridge action", "configure an extension server", "publish to Todoist", or any request involving Todoist UI Extensions SDK, Doist Cards, extension surfaces, the bridge API, or server-side extension development. Load this skill before generating or reviewing any Todoist UI extension code.
Todoist UI Extensions — Developer Reference
Always load the detailed references when working with UI extensions:
references/extension-architecture.md — surfaces, request/response flow, bridge API, lifecyclereferences/doist-cards.md — complete card element and action reference (the card schema bible)references/server-setup.md — Express/NestJS server patterns, auth headers, HMAC, local devreferences/publishing.md — branding rules, certification requirements, submission checklist
Quick Reference
Extension Surfaces
| Surface |
Appears In |
Multiple Allowed |
Key Use Case |
| Context menu |
Project/task right-click menu |
Yes |
Actions on existing items |
| Composer |
Task/comment composer toolbar |
Yes |
Content generation and insertion |
| Settings |
Integration Settings page |
One per app |
Configuration and preferences |
Request/Response Cycle
User triggers extension
→ Todoist sends DoistCardRequest (actionType: "initial")
→ Your server returns DoistCardResponse (card + bridges)
→ Todoist renders card UI
→ User interacts (button click, form submit)
→ Todoist sends DoistCardRequest (actionType: "submit")
→ Your server returns new card or bridges
→ ... repeat until "finished" bridge
Doist Card Root (Required Fields)
{
"type": "AdaptiveCard",
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"doistCardVersion": "0.6",
"version": "1.4",
"body": [],
"actions": []
}
Card Elements Quick Lookup
| Element |
Type Value |
Required Props |
Common Props |
| Text |
TextBlock |
text |
size, weight, color, wrap, isSubtle |
| Rich text |
RichTextBlock |
inlines |
horizontalAlignment |
| Image |
Image |
url |
width, height, altText, size |
| Container |
Container |
— |
items, selectAction, minHeight, bleed |
| Columns |
ColumnSet |
— |
columns |
| Column |
Column |
— |
items, width ("auto"/"stretch") |
| Action group |
ActionSet |
actions |
horizontalAlignment |
Input Elements Quick Lookup
| Input |
Type Value |
Required Props |
Common Props |
| Text field |
Input.Text |
id |
placeholder, label, rows, inputStyle, regex |
| Date picker |
Input.Date |
id |
label, value, min, max |
| Time picker |
Input.Time |
id |
label, value |
| Dropdown/radio |
Input.ChoiceSet |
id, choices |
label, style, isSearchable, orientation |
| Toggle |
Input.Toggle |
id, title |
label, value ("true"/"false") |
Actions Quick Lookup
| Action |
Type Value |
Required Props |
Use Case |
| Submit |
Action.Submit |
— |
Send form data to server |
| Open URL |
Action.OpenUrl |
url |
Navigate to external page |
| Clipboard |
Action.Clipboard |
text |
Copy text |
Bridge Actions
| Bridge |
bridgeActionType |
Key Fields |
Use Case |
| Notify |
display.notification |
notification.text, notification.type |
Show toast |
| Append |
composer.append |
text |
Insert text in composer |
| Sync |
request.sync |
onSuccessNotification, onErrorNotification |
Trigger Todoist sync |
| Finish |
finished |
— |
Close extension modal |
Auth Headers (Incoming)
| Header |
Value |
Purpose |
x-todoist-hmac-sha256 |
Base64(HMAC-SHA256(body, token)) |
Request verification |
x-todoist-apptoken |
Short-lived Bearer token |
API calls from extension |
Key npm Package
@doist/ui-extensions-core
Provides TypeScript types and card builder utilities for Doist Cards.
By