1[:octicons-file-code-24:][_tasklist]{: .source-link }
2
3# Tasklist
4
5## Overview
6
7The Tasklist extension adds GFM style task lists.  They follow the same syntax as GFM. Simply start each list item with
8a square bracket pair containing either a space (an unchecked item) or a `x` (a checked item).
9
10!!! example "Task List Example"
11
12    All task lists in this documentation are generated with [`custom_checkbox`](#options) enabled.
13
14    === "Output"
15        Task List
16
17        - [X] item 1
18            * [X] item A
19            * [ ] item B
20                more text
21                + [x] item a
22                + [ ] item b
23                + [x] item c
24            * [X] item C
25        - [ ] item 2
26        - [ ] item 3
27
28
29    === "Markdown"
30        ```
31        Task List
32
33        - [X] item 1
34            * [X] item A
35            * [ ] item B
36                more text
37                + [x] item a
38                + [ ] item b
39                + [x] item c
40            * [X] item C
41        - [ ] item 2
42        - [ ] item 3
43        ```
44The Tasklist extension can be included in Python Markdown by using the following:
45
46```py3
47import markdown
48md = markdown.Markdown(extensions=['pymdownx.tasklist'])
49```
50
51## Styling with CSS
52
53The HTML structure of a task list is found below:
54
55=== "Default"
56
57    This is the default output.
58
59    ```html
60    <ul class="task-list">
61        <li class="task-list-item">
62            <input type="checkbox" disabled="" checked="">
63            item 1
64        </li>
65    </ul>
66    ```
67
68=== "Custom"
69    If `custom_checkbox` is enabled, the structure will be as follows:
70
71    ```html
72    <ul class="task-list">
73        <li class="task-list-item">
74            <label class="task-list-control">
75                <input type="checkbox" disabled checked="">
76                <span class="task-list-indicator"></span>
77            </label>
78            item 1
79        </li>
80    </ul>
81    ```
82
83=== "Clickable"
84    If `clickable_checkbox` is enabled, user interaction will be allowed by removing the `disabled` attribute from the
85    `input` element. `clickable_checkbox` can be a applied to either the default or custom form.
86
87    ```html
88    <ul class="task-list">
89        <li class="task-list-item">
90            <label class="task-list-control">
91                <input type="checkbox" checked="">
92                <span class="task-list-indicator"></span>
93            </label>
94            item 1
95        </li>
96    </ul>
97    ```
98
99| Classes               | Description                                                                                            |
100| --------------------- | ------------------------------------------------------------------------------------------------------ |
101| `task-list`           | Attached to either the `ul` or `ol` tag and represents the entire list element.                        |
102| `task-list-item`      | This is attached the `li` tag and represents an item in the list.                                      |
103| `task-list-control`   | This is attached to the `label` tag and represents the control object.                                 |
104| `task-list-indicator` | This is attached to the `span` directly following the input and is used to style the visual indicator. |
105
106??? settings "CSS Setup"
107
108    === "Basic Tasklist"
109        In order to style these we mainly remove the list type style and adjust the margins to align with normal list
110        styles.
111
112        ```css
113        .markdown-body .task-list-item {
114          list-style-type: none !important;
115        }
116
117        .markdown-body .task-list-item input[type="checkbox"] {
118          margin: 0 4px 0.25em -20px;
119          vertical-align: middle;
120        }
121        ```
122
123    === "Custom Tasklist"
124
125        If custom check box icons are desired, custom styles can be used to give a unique look to the check marks.
126        Below is a very simple CSS example that creates a light gray square with rounded corners and displays a green
127        Unicode check mark when the control is checked.  This can be adapted to use web fonts, images, etc.
128
129        ```css
130        .markdown-body .task-list-item {
131          list-style-type: none !important;
132        }
133
134        .markdown-body .task-list-item input[type="checkbox"] {
135          margin: 0 4px 0.25em -20px;
136          vertical-align: middle;
137        }
138
139        .markdown-body .task-list-control {
140          display: inline; /* Ensure label is inline incase theme sets it to block.*/
141        }
142
143        .markdown-body .task-list-control {
144          position: relative;
145          display: inline-block;
146          color: #555;
147          cursor: pointer;
148        }
149
150        .markdown-body .task-list-control input[type="checkbox"] {
151          position: absolute;
152          opacity: 0;
153          z-index: -1; /* Put the input behind the label so it doesn't overlay text */
154        }
155
156        .markdown-body .task-list-indicator {
157          position: absolute;
158          top: -8px;
159          left: -18px;
160          display: block;
161          width:  14px;
162          height: 14px;
163          color: #eee;
164          background-color: #eee;
165          border-radius: .25rem;
166        }
167
168        .markdown-body .task-list-control input[type="checkbox"]:checked + .task-list-indicator::before {
169          display: block;
170          margin-top: -4px;
171          margin-left: 2px;
172          font-size: 16px;
173          line-height: 1;
174          content: "✔";
175          color: #1EBB52;
176        }
177        ```
178
179## Options
180
181Option               | Type | Default      | Description
182-------------------- | ---- | ------------ | ------------
183`custom_checkbox`    | bool | `#!py3 False` | Generate task lists in such a way as to allow for styling the check box with CSS.
184`clickable_checkbox` | bool | `#!py3 False` | Enable user to interact with checkboxes.
185