DOC-2898: Documentation enhancements: for https://www.tiny.cloud/docs/tinymce/latest/custom-toggle-toolbar-button/ by jeslynbo · Pull Request #4071 · tinymce/tinymce-docs

jeslynbo · 2026-04-16T01:37:18Z

Ticket: DOC-2898

Site: Staging branch

Changes:

Simplified onSetup event handling and teardown logic
Replacing plain inline code with a cross-referenced API link
Edited comments for onSetup demo
Ensure {product name} is being used correctly

Pre-checks:

Branch prefixed with feature/<version>/, hotfix/<version>/, staging/<version>/, or release/<version>/.
modules/ROOT/nav.adoc has been updated (if applicable).
Included a release note entry for any New product features.
If this is a minor release, updated productminorversion in antora.yml and added new supported versions entry in modules/ROOT/partials/misc/supported-versions.adoc.

Review:

Documentation Team Lead has reviewed

…/tinymce/latest/custom-toggle-toolbar-button/

…criptions for component creation and destruction callbacks.

kemister85

Good improvements overall — the restructured explanation, clearer option/API descriptions, and the formatChanged documentation with unbind() are all valuable. A few issues to fix before merge (suggestions provided inline so you can commit them directly).

kemister85 · 2026-04-27T06:42:24Z

+:keywords: toolbar, toolbarbuttons, buttons, toolbarbuttonsapi, toggle, formatChanged

-A toggle button triggers an action when clicked but also has a concept of state. This means it can be toggled `+on+` and `+off+`. A toggle button gives the user visual feedback for its state through CSS styling. An example of this behavior is the *Bold* button that is highlighted when the cursor is in a word with bold formatting.
+A toggle button triggers an action when clicked and maintains an active state. This means it can be toggled `+on+` or `+off+`. The toggle button provides the user visual feedback of its state through CSS styling. An example of this behavior is the *Bold*, which becomes highlighted when the cursor is within text that has bold formatting.  


Missing the word "button" after Bold, and there's trailing whitespace at end of line.

Suggested change

A toggle button triggers an action when clicked and maintains an active state. This means it can be toggled `+on+` or `+off+`. The toggle button provides the user visual feedback of its state through CSS styling. An example of this behavior is the *Bold*, which becomes highlighted when the cursor is within text that has bold formatting.

A toggle button triggers an action when clicked and maintains an active state. This means it can be toggled `+on+` or `+off+`. The toggle button provides the user visual feedback of its state through CSS styling. An example of this behavior is the *Bold* button, which becomes highlighted when the cursor is within text that has bold formatting.

kemister85 · 2026-04-27T06:42:24Z

+The example above adds two custom *strikethrough* toggle buttons. Both buttons use the xref:editor-command-identifiers.adoc[`+mceToggleFormat+`] command to apply and remove strikethrough formatting. This command toggles a specified format on and off, but only works for xref:content-formatting.adoc#formats[formats] already registered with the editor. In this example, `+strikethrough+` is the registered format.

-The first button applies and removes strikethrough formatting, and its state toggles on click using `+api.setActive(!api.isActive())+`. However, the expected behavior is that the button's state will reflect whether the selected content has strikethrough formatting. For example, if the cursor is moved into editor content that has strikethrough formatting the button will become *active* and if it is moved into content that does not have strikethrough formatting the button will become *inactive*. The first button in the example does not do this, since its state only toggles when the button is clicked.
+=== Basic togle: manual state management


Typo: "togle" → "toggle"

Suggested change

=== Basic togle: manual state management

=== Basic toggle: manual state management

kemister85 · 2026-04-27T06:42:24Z

+The first (`+customStrikethrough+`) button applies and removes strikethrough formatting. Its state toggles upon click using `+api.setActive(!api.isActive())+`. However, this button does not reflect whether the selected content has strikethrough formatting which is its expected behavior. Moving the cursor into content with strikethrough formatting does not activate the button, and moving it out does not deactivate it.

-NOTE: The format name given to `+mceToggleFormat+` via `+editor.execCommand(command, ui, args)+` and to `+editor.formatter.formatChanged(formatName, callback)+` is the same.
+=== State-synced toggle: automatic state updates 


Trailing whitespace after "updates".

Suggested change

=== State-synced toggle: automatic state updates

=== State-synced toggle: automatic state updates

kemister85 · 2026-04-27T06:42:24Z

+The second button (`+customToggleStrikethrough+`) addresses this by using xref:apis/tinymce.formatter.adoc#formatChanged[`+editor.formatter.formatChanged+`] in its `+onSetup+` callback to monitor the formatting state of the current selection.

-For formats that require variables, the `+editor.formatter.formatChanged+` function takes two extra arguments: `+similar+` and `+vars+`.
+Note: The format name passed to +mceToggleFormat+ via +editor.execCommand(command, ui, args)+ is the same as the one used in +editor.formatter.formatChanged(formatName, callback)+.


Two issues here:

Note: should be NOTE: for AsciiDoc admonition rendering.

Inline code needs backtick wrapping (`+code+`) to match the rest of the page — bare +code+ only does passthrough without monospace.

Suggested change

Note: The format name passed to +mceToggleFormat+ via +editor.execCommand(command, ui, args)+ is the same as the one used in +editor.formatter.formatChanged(formatName, callback)+.

NOTE: The format name passed to `+mceToggleFormat+` via `+editor.execCommand(command, ui, args)+` is the same as the one used in `+editor.formatter.formatChanged(formatName, callback)+`.

kemister85 · 2026-04-27T06:42:24Z

+The `+formatChanged+` method accepts the following parameters:

-The `+vars+` argument controls which variables are used to match the content when determining whether to run the callback. This argument is only used when `+similar+` is `+false+`.
+The `+formatChanged+` method accepts the following parameters:


Duplicated paragraph — remove the first occurrence.

Suggested change

The `+formatChanged+` method accepts the following parameters:

The `+vars+` argument controls which variables are used to match the content when determining whether to run the callback. This argument is only used when `+similar+` is `+false+`.

The `+formatChanged+` method accepts the following parameters:

The `+formatChanged+` method accepts the following parameters:

kemister85 · 2026-04-27T06:42:25Z

-The `+vars+` argument controls which variables are used to match the content when determining whether to run the callback. This argument is only used when `+similar+` is `+false+`.
+The `+formatChanged+` method accepts the following parameters:
+
+* `+formats+` (String, required) -- The name of the registered format to monitor.


The formatChanged first parameter accepts a comma-separated list of format names (verified against source: Formatter.ts and the existing API docs at tinymce.formatter.adoc). The current wording implies only a single name.

Suggested change

* `+formats+` (String, required) -- The name of the registered format to monitor.

* `+formats+` (String, required) -- A comma-separated list of registered format names to monitor.

kemister85 · 2026-04-27T06:42:25Z

 ----

-To bind a callback function to an editor event use `+editor.on(eventName, callback)+`. To unbind an event listener use `+editor.off(eventName, callback)+`. Any event listeners _should_ be unbound in the teardown callback. The only editor event which does not need to be unbound is `+init+` e.g. `+editor.on('init', callback)+`.
+To bind a callback function to an editor event use `xref:apis/tinymce.editor.adoc#on[`+editor.off(eventName, callback)+`]. To unbind an event listener use `xref:apis/tinymce.editor.adoc#off[`+editor.off(eventName, callback)+`]. Any event listeners _should_ be unbound in the teardown callback. The only editor event which does not need to be unbound is `+init+` e.g. `+editor.on('init', callback)+`.


Three issues on this line:

Copy-paste error: The first link (for .on) displays editor.off — should be editor.on.

Broken xref syntax: There's an extra leading backtick before each xref:. The codebase pattern is xref:page.adoc#anchor[\+code+`]without a wrapping backtick (seecustomize-ui.adoc, upload-images.adoc` for examples).

Since onSetup.adoc is a shared partial included across multiple pages, these broken links would affect more than just this page.

Suggested change

To bind a callback function to an editor event use `xref:apis/tinymce.editor.adoc#on[`+editor.off(eventName, callback)+`]. To unbind an event listener use `xref:apis/tinymce.editor.adoc#off[`+editor.off(eventName, callback)+`]. Any event listeners _should_ be unbound in the teardown callback. The only editor event which does not need to be unbound is `+init+` e.g. `+editor.on('init', callback)+`.

To bind a callback function to an editor event use xref:apis/tinymce.editor.adoc#on[`+editor.on(eventName, callback)+`]. To unbind an event listener use xref:apis/tinymce.editor.adoc#off[`+editor.off(eventName, callback)+`]. Any event listeners _should_ be unbound in the teardown callback. The only editor event which does not need to be unbound is `+init+` e.g. `+editor.on('init', callback)+`.

DOC-2898: Documentation enhancements: for https://www.tiny.cloud/docs…

99befda

…/tinymce/latest/custom-toggle-toolbar-button/

jeslynbo requested review from a team, kemister85 and soritaheng as code owners April 16, 2026 01:37

jeslynbo requested review from EkimChau and ShiridiGandham April 16, 2026 01:37

jeslynbo marked this pull request as draft April 16, 2026 01:40

DOC-2898: Clarify usage of onSetup in documentation with improved des…

2356bb2

…criptions for component creation and destruction callbacks.

jeslynbo marked this pull request as ready for review April 20, 2026 09:42

kemister85 requested changes Apr 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC-2898: Documentation enhancements: for https://www.tiny.cloud/docs/tinymce/latest/custom-toggle-toolbar-button/#4071

DOC-2898: Documentation enhancements: for https://www.tiny.cloud/docs/tinymce/latest/custom-toggle-toolbar-button/#4071
jeslynbo wants to merge 2 commits intotinymce/8from
hotfix/8/testingPR

jeslynbo commented Apr 16, 2026 •

edited

Loading

Uh oh!

kemister85 left a comment

Uh oh!

kemister85 Apr 27, 2026

Uh oh!

kemister85 Apr 27, 2026

Uh oh!

kemister85 Apr 27, 2026

Uh oh!

kemister85 Apr 27, 2026

Uh oh!

kemister85 Apr 27, 2026

Uh oh!

kemister85 Apr 27, 2026

Uh oh!

kemister85 Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	A toggle button triggers an action when clicked and maintains an active state. This means it can be toggled `+on+` or `+off+`. The toggle button provides the user visual feedback of its state through CSS styling. An example of this behavior is the Bold, which becomes highlighted when the cursor is within text that has bold formatting.
	A toggle button triggers an action when clicked and maintains an active state. This means it can be toggled `+on+` or `+off+`. The toggle button provides the user visual feedback of its state through CSS styling. An example of this behavior is the Bold button, which becomes highlighted when the cursor is within text that has bold formatting.

	=== Basic togle: manual state management
	=== Basic toggle: manual state management

	=== State-synced toggle: automatic state updates
	=== State-synced toggle: automatic state updates

	Note: The format name passed to +mceToggleFormat+ via +editor.execCommand(command, ui, args)+ is the same as the one used in +editor.formatter.formatChanged(formatName, callback)+.
	NOTE: The format name passed to `+mceToggleFormat+` via `+editor.execCommand(command, ui, args)+` is the same as the one used in `+editor.formatter.formatChanged(formatName, callback)+`.

	* `+formats+` (String, required) -- The name of the registered format to monitor.
	* `+formats+` (String, required) -- A comma-separated list of registered format names to monitor.

	To bind a callback function to an editor event use `xref:apis/tinymce.editor.adoc#on[`+editor.off(eventName, callback)+`]. To unbind an event listener use `xref:apis/tinymce.editor.adoc#off[`+editor.off(eventName, callback)+`]. Any event listeners _should_ be unbound in the teardown callback. The only editor event which does not need to be unbound is `+init+` e.g. `+editor.on('init', callback)+`.
	To bind a callback function to an editor event use xref:apis/tinymce.editor.adoc#on[`+editor.on(eventName, callback)+`]. To unbind an event listener use xref:apis/tinymce.editor.adoc#off[`+editor.off(eventName, callback)+`]. Any event listeners _should_ be unbound in the teardown callback. The only editor event which does not need to be unbound is `+init+` e.g. `+editor.on('init', callback)+`.

Conversation

jeslynbo commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kemister85 left a comment

Choose a reason for hiding this comment

Uh oh!

kemister85 Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

kemister85 Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

kemister85 Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

kemister85 Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

kemister85 Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

kemister85 Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

kemister85 Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jeslynbo commented Apr 16, 2026 •

edited

Loading