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[bot]]

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[bot]]

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[bot]]

Yes, that error means your code is trying to access a property (like .attr()) on something that's undefined—most likely because your jQuery selector for .bx-dock-right or .ribbon-tab-container isn't finding any elements when your function runs. In TriliumNext, even onWidgetMount() doesn't guarantee those elements exist yet, since the UI is React-based and elements are rendered dynamically reference.

To fix this, use a pattern that waits for the elements to appear before moving them. Here’s a robust example:

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();

This approach checks if the elements exist, and if not, retries for a few seconds until they do. Also, you only need #widget on your note—#run=frontendStartup isn't needed for widgets reference.

Keep in mind, direct DOM manipulation in a React-based UI can be fragile and may break with future updates. For debugging, you can log the selector results to see which one is missing.

To reply, just mention @dosu.

---

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

[dosubot[bot]]

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}    

[JadeVane]

I modified the code according to the example, but it still doesn't work. Am I using it incorrectly?

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

    tryMoveElement() {
        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;
    }

    onWidgetMount() {
        if (this.tryMoveElement()) {
            return;
        }
        const elementAddedCallback = (mutationsList, observer) => {
            if (this.tryMoveElement()) {
                observer.disconnect();
                this.observer = null; 
            }
        };

        const observerConfig = { childList: true, subtree: true };
        const observer = new MutationObserver(elementAddedCallback);
        
        this.observer = observer;
        observer.observe(document.body, observerConfig);
    }

    onWidgetUnmount() {
        if (this.observer) {
            this.observer.disconnect();
            this.observer = null;
        }
    }
}
module.exports = new MoveElementPlugin();

[eliandoran]

@JadeVane , I would personally avoid using JavaScript to alter the layout. Apart from potential breaking changes if we change the layout on our side, React might not be a permissive as the old jQuery widget system is. Even if you make the change, there's a chance that it will be reverted as soon as that widget re-renders.

What I would recommend instead is to try to use pure CSS. When developing the heavily customized themes on my side (KDE Breeze, GNOME), I used absolute positioning to move things around. It's less likely to break something, but it can be a pain sometimes.

For example you could do something like:

.title-row {
  position: relative;
}

.icon-action.bx-dock-right {
  position: absolute;
  top: calc(100% - 8px);
  right: 4em;
}

[JadeVane]

This is what I did, but using absolute positioning caused other problems. For example, when the enable another plugin, this element will may obscure the button generated by the plugin. That's why I wanted to solve it this way.

However, I will take your suggestion and try to use this method to solve problems as little as possible. Thank you for your suggestion.