Trilium/docs/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets.md

Custom Widgets

Custom widgets are a special subset of scripts that render graphical elements in certain parts of the application. These can be used to add new functionality to the Trilium application.

Preact with JSX vs. vanilla jQuery

In older versions of Trilium, custom widgets were exclusively written in a combination of jQuery with Trilium's internal widget architecture (e.g., BasicWidget, NoteContextAwareWidget).

Starting with v0.101.0, custom widgets can also be written in JSX using the Preact framework. Both legacy and Preact widgets have the same capabilities, with a single difference:

• Preact widgets are content-sized by default whereas legacy widgets need this.contentSized() applied in the constructor. For more information, see the corresponding section in Troubleshooting.

Wherever possible, widget examples will be both in the legacy and Preact format.

Creating a custom widget

1. Create a Code note.
2. Set the language to:
   1. JavaScript (frontend) for legacy widgets using jQuery.
   2. JSX for Preact widgets. You might need to go to Options → Code to enable the language first.
3. Apply the #widget label.

Getting started with a simple example

Let's start by creating a widget that shows a message near the content area. Follow the previous section to create a code note, and use the following content.

Legacy	Preact (v0.101.0+)
class HelloNoteDetail extends api.BasicWidget { constructor() { super(); this.contentSized(); } get parentWidget() { return "center-pane" } doRender() { this.$widget = $("&lt;span&gt;Center pane&lt;/span&gt;"); } } module.exports = new HelloNoteDetail();	import { defineWidget } from "trilium:preact"; export default defineWidget({ parent: "center-pane", render: () => <span>Center pane from Preact.</span> });

Refresh the application and the widget should appear underneath the content area.

Widget location (parent widget)

A widget can be placed in one of the following sections of the applications:

Value for parentWidget	Description	Sample widget	Special requirements
left-pane	Appears within the same pane that holds the Note Tree.	Same as above, with only a different parentWidget.	None.
center-pane	In the content area. If a split is open, the widget will span all of the splits.	See example above.	None.
note-detail-pane	In the content area, inside the note detail area. If a split is open, the widget will be contained inside the split. This is ideal if the widget is note-specific.	Note context aware widget	The widget must export a class and not an instance of the class (e.g. no new) because it needs to be multiplied for each note, so that splits work correctly. Since the class is exported instead of an instance, the parentWidget getter must be static, otherwise the widget is ignored.
right-pane	In the Right Sidebar, as a dedicated section.	Right pane widget	Although not mandatory, it's best to use a RightPanelWidget instead of a BasicWidget or a NoteContextAwareWidget.

To position the widget somewhere else, just change the value passed to get parentWidget() for legacy widgets or the parent field for Preact. Do note that some positions such as note-detail-pane and right-pane have special requirements that need to be accounted for (see the table above).

Launch bar widgets

Launch bar widgets are similar to Custom widgets but are specific to the Launch Bar. See Launch Bar Widgets for more information.

Custom position