ButtonWidget

25th July 2026 at 1:53am

Introduction

The button widget displays an HTML <button> element that can perform a combination of optional actions when clicked:

Executing any ActionWidgets passed in the actions attribute, which is the preferred approach
Executing any ActionWidgets that are immediate children of the button widget, which is now deprecated in favour of using the actions attribute
Execute any integrated actions:
- Navigate to a specified tiddler
- Dispatch a user defined widget message
- Trigger a user defined popup
- Assign new text to a specified tiddler

The integrated actions are provided as a shortcut for invoking common actions. The same functionality is available via ActionWidgets, with the exception of the support for highlighting selected popups.

Content and Attributes

The content of the <$button> widget is displayed within the button.

Attribute	Description
actions	A string containing ActionWidgets to be triggered when the key combination is detected. Introduced in v5.1.23 the modifier variable lists the modifier keys that are pressed when the action is invoked. The possible modifiers are ctrl, ctrl-alt, ctrl-shift, alt, alt-shift, shift and ctrl-alt-shift
to	The title of the tiddler to navigate to
message	The name of the widget message to send when the button is clicked
param	The optional parameter to the message
set	A TextReference to which a new value will be assigned
setTitle	A title to which a new value will be assigned, without TextReference. Gets preferred over `set`
setField	A field name to which the new value will be assigned, if the attribute `setTitle` is present. Defaults to the text field
setIndex	An index to which the new value will be assigned, if the attribute `setTitle` is present
setTo	The new value to assign to the TextReference identified in the `set` attribute or the text field / the field specified through `setField` / the index specified through `setIndex` of the title given through `setTitle`
selectedClass	An optional additional CSS class to be assigned if the popup is triggered or the tiddler specified in `set` already has the value specified in `setTo`
selectedAria	New in v5.4.0 An ARIA attribute to be set to `true` or `false` when `selectedClass` is defined. Allowed values are `aria-checked` (default), `aria-selected` and `aria-pressed`
default	Default value if `set` tiddler is missing for testing against `setTo` to determine `selectedClass`
popup	Title of a state tiddler for a popup that is toggled when the button is clicked. See PopupMechanism for details
popupTitle	Title of a state tiddler for a popup that is toggled when the button is clicked. In difference to the `popup` attribute, no TextReference is used. See PopupMechanism for details
popupAbsCoords	Introduced in v5.2.4 If set to yes writes absolute coordinates to the tiddler referenced by the `popup`. If set to no (the default) uses relative coordinates. See Coordinate Systems for details
aria-label	Optional Accessibility label
role	Introduced in v5.2.3 Optional ARIA role
tooltip	Optional tooltip
class	An optional CSS class name to be assigned to the HTML element
data-*	New in v5.3.2 Optional data attributes to be assigned to the HTML element
style.*	New in v5.3.2 Optional CSS properties to be assigned to the HTML element
aria-*	New in v5.4.0 Optional ARIA attributes.
style	An optional CSS style attribute to be assigned to the HTML element
tag	An optional html tag to use instead of the default "button"
dragTiddler	An optional tiddler title making the button draggable and identifying the payload tiddler. See DraggableWidget for details
dragFilter	An optional filter making the button draggable and identifying the list of payload tiddlers. See DraggableWidget for details
tabindex	Sets the `tabindex` attribute of the button to the given value
disabled	Introduced in v5.1.23 Optional, disables the button if set to "yes". Defaults to "no"

Note: In almost all other cases where a TextReference is used as a widget attribute, it will be placed between curly brackets, to transclude the value currently stored there. However, when we use a TextReference as the value of a button widget's set attribute, we are referencing the storage location itself, rather than the value stored there, so we do not use curly brackets there. Example: we could code a button widget that sets the caption field of TiddlerA to be the same as that of TiddlerB as:

Tip

Introduced in v5.1.18 setTitle, setField and setIndex attributes allow specifying Tiddler states directly, without interpreting them as TextReferences. This is useful for edge-cases where titles may contain characters that are used to denote Tiddler fields or indices (!!, ##)

<$button set="TiddlerA!!caption" setTo={{TiddlerB!!caption}} >

Press me!

</$button>

Order of execution

The order of the attributes written in wikitext does not matter.

A button can carry several of these attributes at once. They are not alternatives: every one that is present is used, and always in the order shown below.

ActionWidgets in the button body
to
message, with param
popup or popupTitle
set or setTitle, with setTo, setField and setIndex
actions

Tip

When a button does more than one thing, put the whole behaviour in the actions attribute. It keeps the behaviour in one place and runs it last, after every other attribute above. A single <$button to="HelloThere">Click Me</$button> needs no action string.

Action widgets are refreshed before each one runs, so they see the results of the actions before them. Ordinary widgets wrapped around them are not. See ActionWidget Execution Modes when a value looks out of date.

Examples

This button uses the to attribute to navigate to the HelloThere tiddler, opening it in the story river. The optional tooltip attribute sets the text shown on hover.

<$button to="HelloThere" tooltip="Navigate to the HelloThere tiddler">
Open ~HelloThere
</$button>

That renders as:

Tip

Set class to tc-btn-invisible tc-tiddlylink to have a button look like an internal link.

Interactive Examples

ButtonWidget/Example/Accessibility
Add accessibility and metadata attributes such as aria-label, role, tabindex and data
ButtonWidget/Example/Actions
Run one or more ActionWidgets when the button is clicked, using the preferred actions attribute
ButtonWidget/Example/DragAndDrop
Make a button draggable with dragTiddler or dragFilter
ButtonWidget/Example/DragFilter
Drag a list of tiddlers with dragFilter and receive it with listActions
ButtonWidget/Example/Message
Send a widget message with the message and param attributes
ButtonWidget/Example/NewTiddler
Create a tiddler from a template with the tm-new-tiddler message
ButtonWidget/Example/Popup
Toggle a popup with the popup attribute and a companion reveal widget
ButtonWidget/Example/Presentation
Change the rendered element and appearance with tag, class, style and disabled
ButtonWidget/Example/SelectedState
Highlight the active button with selectedClass, set, setTo and default used together
ButtonWidget/Example/SetAndSetTo
Assign a value to a tiddler with the set and setTo attributes used together
ButtonWidget/Example/SetField
Assign a field or index directly with setTitle, setField and setIndex