Todoist Cards, which are returned in the response from the extension and rendered by the Todoist client for the user, are based on Adaptive Cards.
The Todoist Cards schema is based on the Adaptive Cards schema and provides the elements currently supported in the Todoist clients. We aim for all current versions of Todoist clients to support the latest version of the Todoist Cards schema.
Todoist Cards Versions
| Todoist Cards Version | Notes |
|---|---|
| 0.6 | Latest |
How to Use
The spec below loosely follows the official Schema Explorer. It lists all the elements supported in Todoist Cards SDKs. The Version column is the Todoist Cards Version, not the Adaptive Cards version.
Card
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "AdaptiveCard". |
0.6 |
|
$schema String |
Yes | Must be "http://adaptivecards.io/schemas/adaptive-card.json".
|
0.6 |
|
todoistCardVersion String |
Yes | Declares compatibility with a specific version of Todoist Cards. It is set to 0.6 on the latest Todoist Card version. |
0.6 |
|
version String |
Yes | The Adaptive Card schema version. It is set to 1.4 on the latest Todoist Card version. |
0.6 |
| bodyList of Elements | Yes | The card elements to show in the primary card region. | 0.6 |
| actionsList of Actions | No | The actions to show in the card's bottom action bar. | 0.6 |
|
autoFocusId String |
No | The ID of the input the card wishes to get focus when the card is rendered. | 0.6 |
Element
All Card Elements, Containers, and Inputs extend Element and support the below properties.
| Property | Required | Description | Version |
|---|---|---|---|
|
id String |
No | A unique identifier associated with the item. | 0.6 |
|
spacing |
No | The amount of spacing between this element and the preceding element. | 0.6 |
|
separator Boolean |
No | When true, draw a separating line between this element and the preceding element. | 0.6 |
Card Elements
TextBlock
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "TextBlock". |
0.6 |
|
text String |
Yes | Text to display. | 0.6 |
|
size |
No | Font size of the rendered text. | 0.6 |
|
isSubtle Boolean |
No | If true, displays text slightly toned down to appear less prominent. |
0.6 |
|
horizontalAlignment |
No | The horizontal alignment of the TextBlock. | 0.6 |
|
weight |
No | Controls the weight of the TextBlock element. | 0.6 |
|
color |
No | Controls the foreground color of the TextBlock element. | 0.6 |
|
wrap Boolean |
No | If true, allow text to wrap. Otherwise, text is clipped. | 0.6 |
Image
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Image". |
0.6 |
|
url String |
Yes | The URL to the image. | 0.6 |
|
selectAction |
No | An Action that will be invoked when the Image is tapped or selected. | 0.6 |
|
width String |
No | The desired on-screen width of the image, ending in px. E.g., 50px. |
0.6 |
|
height String |
No | The desired height of the image. If specified as a pixel value, ending in px, E.g., 50px, the image will distort to fit that exact height. |
0.6 |
|
altText String |
No | Alternate text describing the image. | 0.6 |
|
aspectRatio Number |
No | The aspect ratio of the image if height/width are known. | 0.6 |
|
size |
No | Controls the approximate size of the image. The physical dimensions will vary per host. | 0.6 |
RichTextBlock
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "RichTextBlock". |
0.6 |
|
inlines List of Inlines |
Yes | The array of inlines. | 0.6 |
|
horizontalAlignment |
No | The horizontal alignment of the RichTextBlock. | 0.6 |
Inline
Inline can be of type String or TextRun.
TextRun
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "TextRun". |
0.6 |
|
text String |
Yes | Text to display. | 0.6 |
|
color |
No | Controls the foreground color of the TextBlock element. | 0.6 |
|
size |
No | Font size of the rendered text. | 0.6 |
|
isSubtle Boolean |
No | If true, displays text slightly toned down to appear less prominent. |
0.6 |
|
weight |
No | Controls the weight of the TextBlock element. | 0.6 |
|
selectAction |
No | Action to invoke when the TextRun is clicked. Visually changes the text run into a hyperlink. | 0.6 |
Containers
ActionSet
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "ActionSet". |
0.6 |
|
actions List of Actions |
Yes | The array of Action elements to show. | 0.6 |
|
horizontalAlignment |
No | The horizontal alignment of the ActionSet. | 0.6 |
Container
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Container". |
0.6 |
|
items List of Elements |
No | The card elements to render inside the Container. | 0.6 |
|
selectAction |
No | An Action that will be invoked when the Container is tapped or selected. | 0.6 |
|
minHeight String |
No | Specifies the minimum height of the container in pixels, like "80px". | 0.6 |
|
backgroundImage |
No | Specifies the background image. Acceptable formats are PNG, JPEG, and GIF. | 0.6 |
|
verticalContentAlignment |
No | Defines how the content should be aligned vertically within the container. If not specified "top" is the default. |
0.6 |
|
bleed Boolean |
No | Determines whether the element should bleed through its parent's padding. | 0.6 |
ColumnSet
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "ColumnSet". |
0.6 |
|
columns List of Columns |
No | The array of Column to divide the region into. |
0.6 |
|
horizontalAlignment |
No | The horizontal alignment of the ColumnSet. | 0.6 |
Column
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Column". |
0.6 |
|
items List of Elements |
No | The card elements to render inside the Column. | 0.6 |
|
verticalContentAlignment |
No | Defines how the content should be aligned vertically within the column. | 0.6 |
|
width String |
No | Either "auto" or "stretch". Note that "3px" format might be supported in future versions of Todoist Cards. |
0.6 |
|
selectAction |
No | An Action that will be invoked when the Column is tapped. | 0.6 |
Actions
All Actions support the following properties:
| Property | Required | Description | Version |
|---|---|---|---|
|
id String |
No | A unique identifier associated with the item. | 0.6 |
|
title String |
No | Label for button or link that represents this action. | 0.6 |
|
iconUrl String |
No | Optional icon to be shown on the action in conjunction with the title. Supports data URI. | 0.6 |
|
style |
No | Appearance of the action. | 0.6 |
Action.Submit
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Action.Submit". |
0.6 |
|
data String or Object |
No | Initial data that input fields will be combined with. These are essentially "hidden" properties. | 0.6 |
|
associatedInputs |
No | Controls which inputs are associated with the submit action.Default is "Auto". | 0.6 |
Action.OpenUrl
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Action.OpenUrl". |
0.6 |
|
url String |
Yes | The URL that will be opened when the action is invoked. | 0.6 |
Action.Clipboard
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Action.Clipboard". |
0.6 |
|
text String |
Yes | The text that will be copied to the clipboard when the action is invoked. | 0.6 |
Inputs
Input.Text
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Input.Text". |
0.6 |
|
placeholder String |
No | Description of the input desired. Displayed when no text has been input. | 0.6 |
|
inlineAction |
No | The inline action for the input. Typically displayed to the right of the input. It is strongly recommended to provide an icon on the action (which will be displayed instead of the title of the action). | 0.6 |
|
label String |
No | Label for this input. | 0.6 |
|
isRequired Boolean |
No | Whether or not this input is required. | 0.6 |
|
errorMessage String |
No | Error message to display when entered input is invalid. | 0.6 |
|
rows Number |
No | The number of rows a multi-line text input should display. | 0.6 |
|
inputStyle |
No | The style the text input should display as. | 0.6 |
|
value String |
No | The initial value for this field. | 0.6 |
|
regex String |
No | Regular expression indicating the required format of this text input. | 0.6 |
Input.Date
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Input.Date". |
0.6 |
|
label String |
No | Label for this input. | 0.6 |
|
isRequired Boolean |
No | Whether or not this input is required. | 0.6 |
|
errorMessage String |
No | Error message to display when entered input is invalid. | 0.6 |
|
value String |
No | The initial value for this field, in the format YYYY-MM-DD. |
0.6 |
|
min String |
No | The minimum inclusive value for the field, in the format YYYY-MM-DD. |
0.6 |
|
max String |
No | The maximum inclusive value for the field, in the format YYYY-MM-DD. |
0.6 |
Input.Time
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Input.Time". |
0.6 |
|
label String |
No | Label for this input. | 0.6 |
|
isRequired Boolean |
No | Whether or not this input is required. | 0.6 |
|
errorMessage String |
No | Error message to display when entered input is invalid. | 0.6 |
|
value String |
No | The initial value for this field, in the format HH:mm. |
0.6 |
Input.ChoiceSet
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Input.ChoiceSet". |
0.6 |
|
label String |
No | Label for this input. | 0.6 |
|
isRequired Boolean |
No | Whether or not this input is required. | 0.6 |
|
errorMessage String |
No | Error message to display when entered input is invalid. | 0.6 |
|
value String |
No | Thevalueof the initial choice. | 0.6 |
|
choices Object |
Yes | An array of Choices. | 0.6 |
|
selectAction |
No | An Action that will be invoked when the selection is changed. | 0.6 |
|
isSearchable Boolean |
No | Sets whether this list of choices is searchable and the text value can be free-form. | 0.6 |
|
style |
No | Sets what style the ChoiceSet should use. Default is compact. |
0.6 |
|
orientation |
No | Sets what style the ChoiceSet should use. Default is compact. |
0.6 |
Choice
Describes a choice for use in a ChoiceSet.
| Property | Required | Description | Version |
|---|---|---|---|
|
title String |
Yes | Text to display. | 0.6 |
|
value String |
No | The raw value of the choice. | 0.6 |
|
disabled Boolean |
No | If true, the option will render as disabled. |
0.6 |
Input.Toggle
| Property | Required | Description | Version |
|---|---|---|---|
|
type String |
Yes | Must be "Input.Toggle". |
0.6 |
|
title String |
Yes | Title for the toggle. | 0.6 |
|
id String |
Yes | Unique identifier for the value. Used to identify collected input when the Submit action is performed. | 0.6 |
|
value String |
No | The initial selected value. This will return "true" or "false". If you want the toggle to be initially on, set this to "true". |
0.6 |
|
wrap Boolean |
No | If true, allw text to wrap, otherwise text is clipped. |
0.6 |
|
label String |
No | Label for this input. | 0.6 |
|
isRequired Boolean |
No | Whether or not this input is required. | 0.6 |
|
errorMessage String |
No | Error message to display when entered input is invalid. | 0.6 |
|
selectAction |
No | An Action that will be invoked when the checked status is changed. | 0.6 |
Types
BackgroundImage
| Value | Required | Description | Version |
|---|---|---|---|
|
url String |
Yes | URL of the background image. | 0.6 |
|
fillMode |
No | Describes how the image should fill the area. If none specified, cover is applied. |
0.6 |
Enums
Spacing
Please note: The values sent for this are case insensitive
| Value | Version |
|---|---|
| default | 0.6 |
| none | 0.6 |
| small | 0.6 |
| medium | 0.6 |
| large | 0.6 |
HorizontalAlignment
Please note: The values sent for this are case insensitive
| Value | Version |
|---|---|
| left | 0.6 |
| center | 0.6 |
| right | 0.6 |
VerticalContentAlignment
Please note: The values sent for this are case insensitive
| Value | Version |
|---|---|
| top | 0.6 |
| center | 0.6 |
| bottom | 0.6 |
FontWeight
Please note: The values sent for this are case insensitive
| Value | Version |
|---|---|
| lighter | 0.6 |
| default | 0.6 |
| bolder | 0.6 |
FontSize
Please note: The values sent for this are case insensitive
| Value | Version |
|---|---|
| default | 0.6 |
| small | 0.6 |
| medium | 0.6 |
| large | 0.6 |
| extraLarge | 0.6 |
Color
Please note: The values sent for this are case insensitive
| Value | Version |
|---|---|
| default | 0.6 |
| dark | 0.6 |
| light | 0.6 |
| accent | 0.6 |
| good | 0.6 |
| warning | 0.6 |
| attention | 0.6 |
ImageFillMode
Please note: The values sent for this are case insensitive
| Value | Description | Version |
|---|---|---|
| cover | The background image covers the entire width of the container. Its aspect ratio is preserved. Content may be clipped if the aspect ratio of the image doesn't match the aspect ratio of the container. verticalAlignment is respected (horizontalAlignment is meaningless since it's stretched width). This is the default mode and is the equivalent to the current model. |
0.6 |
| repeat | The background image isn't stretched. It is repeated first in the x axis then in the y axis as many times as necessary to cover the entire container. Both horizontalAlignment and verticalAlignment are honored (defaults are left and top). |
0.6 |
ActionStyle
Please note: The values sent for this are case insensitive
| Value | Description | Version |
|---|---|---|
| default | Action is displayed as normal. | 0.6 |
| positive | Action is displayed with a positive style (typically the button becomes accent color). | 0.6 |
| destructive | Action is displayed with a destructive style (typically a red, warning-like design). | 0.6 |
InputStyle
Please note: The values sent for this are case insensitive
| Value | Description | Version |
|---|---|---|
| text | This is a regular text input. | 0.6 |
| tel | This is a number (eg, telephone) input. | 0.6 |
| This is an email input. | 0.6 | |
| url | This is a URL input. | 0.6 |
| search | This is a search box input. | 0.6 |
ImageSize
Please note: The values sent for this are case insensitive
| Value | Description | Version |
|---|---|---|
| auto | Image will scale down to fit if needed, but will not scale up to fill the area. | 0.6 |
| stretch | Image with both scale down and up to fit as needed. | 0.6 |
| small | Image is displayed with a fixed small width, where the width is determined by the host. | 0.6 |
| medium | Image is displayed with a fixed medium width, where the width is determined by the host. | 0.6 |
| large | Image is displayed with a fixed large width, where the width is determined by the host. | 0.6 |
ChoiceInputStyle
| Value | Description | Version |
|---|---|---|
| compact | This will make the choices appear as a dropdown. | 0.6 |
| expanded | This will make the choices appear as radio buttons, only applies if isMultiSelect is false. |
0.6 |
Orientation
| Value | Description | Version |
|---|---|---|
| vertical | Has a vertical orientation. | 0.6 |
| horizontal | Has a horizontal orientation. | 0.6 |
AssociatedInput
| Value | Description | Version |
|---|---|---|
| auto | Inputs on the current card and any parent cards will be validated and submitted for this Action. | 0.6 |
| none | None of the inputs will be validated or submitted for this Action. | 0.6 |
| ignorevalidation | Ignores any validation but still submits the input values for the Action. |
Get in touch
If you still have questions about Todoist cards or want to learn more, get in touch with us.