This page is part of a static HTML representation of the TiddlyWiki at


8th June 2019 at 4:24pm
Lists Widgets


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.


plain list

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

Displays as:


custom item output

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

Displays as:


Lists ListWidget

custom item template

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

Displays as:

21st February 2015 at 11:01pm

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.

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
filterThe tiddler filter to display
templateThe title of a template tiddler for transcluding each tiddler in the list. When no template is specified, the body of the ListWidget serves as the item template. With no body, a simple link to the tiddler is returned.
editTemplateAn alternative template to use for DraftTiddlers in edit mode
variableThe name for a variable in which the title of each listed tiddler is stored. Defaults to currentTiddler
emptyMessageMessage to be displayed when the list is empty
storyviewOptional name of module responsible for animating/processing the list
historyThe title of the tiddler containing the navigation history

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