Introduction

The list widget displays a sequence of tiddlers that match a tiddler filter. It can be used for many purposes:

• Displaying custom lists of links, like in TiddlyWiki5's sidebar
• Custom lists, such as "all tiddlers tagged 'task' that are not tagged 'done'"
• Listing each of the tags applied to a tiddler
• Handling the main story river

The tiddlers are displayed by transcluding each in turn through a template. There are several ways to specify the template and for controlling the behaviour of the list.

Examples

plain list

<$list filter="[tag[ListWidget]sort[title]]"/>

Displays as:

GroupedLists

custom item output

<$list filter="[tag[ListWidget]sort[title]]">
<<currentTiddler>>
{{||$:/core/ui/ViewTemplate/tags}}
</$list>

Displays as:

GroupedLists

ListsListWidget

custom item template

<$list filter="[tag[ListWidget]sort[title]]" template="$:/core/ui/ViewTemplate/subtitle"/>

Displays as:

4th December 2024 at 8:56am

Grouped Lists

See GroupedLists for how to generate nested and grouped lists using the ListWidget.

Content and Attributes

The content of the <$list> widget is an optional template to use for rendering each tiddler in the list.

New in v5.3.2 If the widgets <$list-template> or <$list-empty> are found as immediate children of the $ListWidget widget then the content of those widgets are used as the list item template and/or the empty template. Note that the emptyMessage and template attributes take precedence if they are present.

The action of the list widget depends on the results of the filter combined with several options for specifying the template:

• If the filter evaluates to an empty list, the text of the emptyMessage attribute is rendered, and all other templates are ignored
• Otherwise, if the template attribute is specified then it is taken as the title of a tiddler to use as a template for rendering each item of the list
• Otherwise, if the list widget content is not blank, it is used as a template for rendering each item of the list
• Otherwise, a default template is used consisting of a <span> or <div> element wrapped around a link to the item

counter attribute

The optional counter attribute specifies the name of a variable to hold the 1-based numeric index of the current item in the list.

Two additional variables are also set to indicate the first and last items in the list:

• <counter-variable-name>-first is set to yes for the first entry in the list, no for the others
• <counter-variable-name>-last is set to yes for the last entry in the list, no for the others

For example:

<$list filter="[tag[About]sort[title]]" counter="counter">
<div>
<<counter>>: ''<$text text=<<currentTiddler>>/>'' (is first: <<counter-first>>, is last: <<counter-last>>)
</div>
</$list>

Displays as:

1: Acknowledgements (is first: yes, is last: no)

2: Contributors (is first: no, is last: no)

3: Funding TiddlyWiki (is first: no, is last: no)

4: History of TiddlyWiki (is first: no, is last: no)

5: License (is first: no, is last: no)

6: Open Collective (is first: no, is last: no)

7: Releases (is first: no, is last: no)

8: RoadMap (is first: no, is last: no)

9: TiddlyWiki Archive (is first: no, is last: yes)

Note that using the counter attribute can reduce performance when working with list items that dynamically reorder or update themselves. The best advice is only to use it when it is really necessary: to obtain a numeric index, or to detect the first or last entries in the list. Note that if you are only using it to insert something (like a comma) between list items, the join attribute performs much better and you should use it instead of counter.

Setting counter="transclusion" is a handy way to make child elements for each list element be identified as unique. A common use case are multiple tag macros for the same tag generated by a list widget. Refer to tag macro examples for more details.

join attribute

New in v5.3.2 The optional join attribute allow you to insert some WikiText between each list item without needing to use the counter attribute, which can become quite slow if the list is updated frequently.

New in v5.3.2 If the widget <$list-join> is found as an immediate child of the $ListWidget widget then the content of that widget is used as the "join" template, included between two list items. Note that the join attribute takes precedence if it is present.

For example:

<$list filter="[tag[About]sort[title]]" join=", " variable="item"><<item>></$list>

Displays as:

Acknowledgements, Contributors, Funding TiddlyWiki, History of TiddlyWiki, License, Open Collective, Releases, RoadMap, TiddlyWiki Archive

Edit mode

The <$list> widget can optionally render draft tiddlers through a different template to handle editing, see DraftMechanism.

storyview attribute

The storyview attribute specifies the name of an optional module that can animate changes to the list (including navigation). The core ships with the following storyview modules:

• classic: renders the list as an ordered sequence of tiddlers
• zoomin: just renders the current tiddler from the list, with a zoom animation for navigating between tiddlers
• pop: shrinks items in and out of place

In order for the storyviews to animate correctly each entry in the list should be a single block mode DOM element.

History and navigation

The optional history attribute specifies the name of a tiddler that is used to track the current tiddler for navigation purposes. When the history tiddler changes the list view responds by telling the listview to handle navigating to the new tiddler. See HistoryMechanism for details.

Additional Notes and Edge Cases

• If the filter attribute is not present then a default of [!is[system]sort[title]] is used
• If the list widget is completely empty (ie only whitespace between the opening and closing tags), then it behaves as if the content were a DIV or a SPAN containing a link to the current tiddler (it’s a DIV if the list widget is in block mode, or a SPAN if it is in inline mode)
• If the template attribute is not present then the content of the list widget will be used as the template, unless the widget is completely empty in which case a default template is used