Element API against document/document.documentElement/html?

Matti · August 6, 2025, 7:36am

I’m working with Java API for some handy browser APIs and it would be really handy to have “Element API” agains the html element. I wonder if I’m missing some method to get one? UI.getElement() gives me document.body, which is the closest one, but not enough for my need.

knoobie · August 6, 2025, 7:41am

I doubt that there is an API available… it kinda reminds me of this discussion UI.getCurrent().getComponent() in WebComponent returns body-Element · Issue #19133 · vaadin/flow · GitHub

Jouni1 · August 6, 2025, 7:42am

Such API would be welcomed, to easily set the theme attribute value on the <html> element.

Tatu2 · August 6, 2025, 7:44am

We do have AppShellConfigurator and configurePage (and the old BootstraplListener that is echo from Vaadin 8 still exists). But I would assume @Matti is trying to figure out something that is more straightforward to use.

Matti · August 6, 2025, 7:49am

This is not the first time I have missed this, but now just started to wonder if I’m really just not discovering this features. I have a workaround, but it is ugly and my tooling is probably broken if the app is embedded as web component…

I have no idea if it is possible to implement, but maybe the Page object would be most logical place for one

AppShellConfigurator is useless for my case.

Matti · August 6, 2025, 7:54am

Here is the “workaround” I have used (and will use again). I’ll kind of piggypack the events from document (etc) and dispatch them as custom events on body and then I can listen to them via UI.getElement():

github.com

viritin/flow-viritin/blob/v24/src/main/java/org/vaadin/firitin/util/PageVisibility.java#L77


      
          }
          
          /**
           * Adds a listener for visibility change events on the page. In the browser, this is
           * uses both the `visibilitychange` event and the `blur` and `focus` events to determine
           * the visibility and focusing state of the page.
           *
           * @param listener the listener to be notified when the visibility state changes.
           * @return a DomListenerRegistration that can be used to remove the listener later.
           */
          public Registration addVisibilityChangeListener(PageVisibilityListener listener) {
              if (domListenerRegistration == null) {
                  /*
                   * Browser differences makes the implementation a bit more complex. Some notes:
                   *
                   *   - firefox defers visibilitychange events
                   *   - sofari fires some duplicate focus events
                   */
          
                  ui.getPage().executeJs("""
                          document.addEventListener('visibilitychange', function() {

Tatu2 · August 6, 2025, 7:59am

Page object could have some utility API for JavaScript calls, like

    public void setAttribute(String attribute, String value) {
        executeJs("document.querySelector('html').setAttribute(%0, %1);",
                attribute, value);
    }

Matti · August 6, 2025, 8:09am

That would not help in my case at all, might be enough for the theme attribute.

Tatu2 · August 6, 2025, 8:37am

True, you seem to be longing for page.getElement(), but the problem with that is that would be rather special Node feature in our NodeTree, i.e. Flow internal bookkeeping of elements and stuff. And this would be something that is should be skipped when producing the JSON containing the updates for Flow client. I would assume it would be there in the bottom always. I.e. added immediatelly when at UI object instantiation. I think it is technically possible, not trivial and requires careful thinking in order not to break things and causing weird side effects.

Matti · August 6, 2025, 8:45am

Like the title says, I’m longing for the Element API for the document. Page is pretty much equivalent to window, so getElement() there would not be logical. Quickly thinking the method name out to be more like getDocumentElement() instead. But it might be that a better approach would be to introduce a separate Document helper class instead.

Matti · August 6, 2025, 2:38pm

My today’s workaround documented here:

github.com

viritin/flow-viritin/blob/v24/src/main/java/org/vaadin/firitin/util/fullscreen/FullScreen.java#L131-L150


      
          public static Registration addFullscreenChangeListener(ComponentEventListener<FullscreenChangeEvent> listener) {
              // conditionally add a listener to document.documentElement that re-fires events with a different name
              // on document.body (~ UI)
              UI ui = UI.getCurrent();
              ui.getPage().executeJs("""
                          if(!document.__viritin_fullscreen_change_listener) {
                              document.addEventListener('fullscreenchange', () => {
                                  const isFullscreen = document.fullscreenElement !== null;
                                  document.body.dispatchEvent(new CustomEvent('viritin-fullscreenchange', {
                                      detail: isFullscreen
                                  }));
                              });
                          }
                          document.__viritin_fullscreen_change_listener = true;
                      """);
          
              return ui.getElement().addEventListener("viritin-fullscreenchange", event -> {
                  boolean isFullscreen = event.getEventData().getBoolean("event.detail");
                  listener.onComponentEvent(new FullscreenChangeEvent(ui, isFullscreen));
              }).addEventData("event.detail");

Leif · August 13, 2025, 10:18am

I have a wild dream of making it possible to get a server-side proxy for any JS object, i.e. not only things that would make sense as a Element but also any other kind of object. Additionally, I’m thinking of making it really easy to generate Java interfaces for such objects based on TS definitions.

In the mean time, I suspect it could be a relatively simple Flow PR to add a hardcoded Element proxy specifically for document. Could be useful to have one for window as well.