How to move elements within a custom theme

[JadeVane]

Some time ago, I created a theme called Allure, but I stopped updating it for a long time due to being too busy. Recently, while reviewing the code, I discovered that this theme has some style errors in the new version of TriliumNext, and it indicates that this theme is an old theme. I'm not sure how to make this theme new, but that's not the most important issue. I've realized that many functions that were previously implemented using CSS can be better implemented using JavaScript, so I'd like to spend some time migrating the theme.

A typical example is changing the position of elements. For instance, I want to move the child element .bx-dock-right of .title-row into .ribbon-tab-container and make it the first element. To do this, I wrote my own version based on the JavaScript for wordCount and added #run=frontendStartup #widget to the attributes.

class MoveElementPlugin extends api.NoteContextAwareWidget {
get parentWidget() { return 'center-pane'; }

moveDockRightElement() {
const $dockRight = $('.bx-dock-right');
const $ribbonTabContainer = $('.ribbon-tab-container');
const $firstRibbonTab = $ribbonTabContainer.children().first();
$dockRight.insertBefore($firstRibbonTab);
}
}
module.exports = new MoveElementPlugin();

This seems impossible. Where did I go wrong?

[dosubot]

Hi @JadeVane! I'm Dosu and I’m helping the Trilium team.

Your code isn't working because TriliumNext's frontend widgets (like those using #run=frontendStartup #widget) execute very early—often before the DOM elements you want to move actually exist. This means your selectors may return empty results, so nothing gets moved. Also, TriliumNext's UI is now React-based, so elements like .bx-dock-right and .ribbon-tab-container are rendered dynamically, and direct DOM manipulation is less reliable than before.

To fix this, you need to wait until the DOM is fully rendered before running your move logic. In practice, you can use a MutationObserver or repeatedly check for the presence of both elements before moving them. Here’s a robust pattern:

class MoveElementPlugin extends api.NoteContextAwareWidget {
  get parentWidget() { return 'center-pane'; }

  moveDockRightElement() {
    const tryMove = () => {
      const $dockRight = $('.bx-dock-right');
      const $ribbonTabContainer = $('.ribbon-tab-container');
      if ($dockRight.length && $ribbonTabContainer.length) {
        const $firstRibbonTab = $ribbonTabContainer.children().first();
        $dockRight.insertBefore($firstRibbonTab);
        return true;
      }
      return false;
    };

    // Try immediately, then poll every 100ms until successful or timeout
    if (!tryMove()) {
      let attempts = 0;
      const interval = setInterval(() => {
        if (tryMove() || ++attempts > 50) clearInterval(interval);
      }, 100);
    }
  }

  onWidgetMount() {
    this.moveDockRightElement();
  }
}
module.exports = new MoveElementPlugin();

Make sure to call your logic from onWidgetMount() or a similar lifecycle method, not the constructor. This ensures your code runs after the widget is attached and the DOM is more likely to be ready.

Keep in mind: since TriliumNext is React-based, direct DOM manipulation can be fragile—future updates may break this approach. If you want a more stable solution, consider contributing to the codebase or requesting a supported extension point for UI customization.

For more on widget lifecycle and best practices, see the TriliumNext developer guide.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[JadeVane]

I'm still experimenting with how to tweak the interface to achieve the design intent, so it's not the right time to submit a pull request. I'm also unsure how much time I can ultimately dedicate to it, and whether it will sustainably help improve bugs. Therefore, using a theme for now is the best approach.

Make sure to call your logic from onWidgetMount() or a similar lifecycle method, not the constructor.

What should I do? Should I add #widget to the properties?

[dosubot]

Yes, you should add #widget to your note's properties. This tells Trilium to treat your note as a frontend widget, enabling its JavaScript to run in the UI and participate in the widget lifecycle. For UI tweaks like DOM manipulation, put your logic in the onWidgetMount() method (not the constructor), since this runs after the widget is attached and the DOM is more likely to be ready for changes cite cite.

You do not need #run=frontendStartup for widgets—just #widget is enough. Make sure your widget class defines get parentWidget() to specify where it attaches (e.g., 'center-pane'). After editing the widget note, restart Trilium to apply changes cite.

This approach is recommended for experimenting with UI tweaks in a theme context cite.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[JadeVane]

Thank you for your patient explanation. I'm not familiar with React, and I'm trying to understand it.

I used the sample code you provided directly, and added #widget, and confirmed that the loading time is explicitly specified in the code.

onWidgetMount() {
this.moveDockRightElement();
}

However, the error message "Cannot read properties of undefined (reading 'attr')" still appears. Does this mean that the DOM is not yet ready?

[dosubot]

The error means your code is trying to access a property (like .attr()) on an object that is undefined—most likely because the jQuery selector for .bx-dock-right or .ribbon-tab-container isn't finding anything when your function runs. In TriliumNext's React-based UI, these elements may not exist yet when your widget's lifecycle methods (even onWidgetMount) are called, so direct DOM manipulation is unreliable at that point example.

To fix this, always check that your selectors return elements before you use them. For example:

const $dockRight = $('.bx-dock-right');
const $ribbonTabContainer = $('.ribbon-tab-container');
if ($dockRight.length && $ribbonTabContainer.length) {
  // safe to manipulate
}

If the elements aren't present, use a polling loop or a MutationObserver to wait for them to appear before running your move logic example. This pattern is common for Trilium widgets that need to interact with dynamically rendered DOM.

Let me know if you want a MutationObserver example or help debugging your selectors!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}