Advanced DOM & Interop

SPRAG components should own most rendering through render(). This page covers the supported dom.* helper surface when you need direct DOM work.

Query and visibility

Use the query helpers and visibility helpers for lightweight DOM control:

from sprag import Module, dom

class PanelModule(Module):
    def on_start(self):
        btn = dom.query("[data-role='toggle']", self.element)
        panel = dom.query(".panel", self.element)
        self.on(btn, "click", lambda event: dom.toggle(panel))

Available helpers:

• dom.query(selector, parent=None)
• dom.query_all(selector, parent=None)
• dom.show(element)
• dom.hide(element)
• dom.toggle(element)

Styling and attributes

dom.css(panel, {"display": "grid", "gap": "8px"})
dom.attr(panel, {"data-state": "open", "aria-hidden": "false"})

Available helpers:

• dom.css(element, styles)
• dom.attr(element, attrs)
• dom.clear(element)

DOM mutation

item = dom.query(".item", self.element)
list_el = dom.query(".list", self.element)

dom.append(list_el, item)
dom.prepend(list_el, item)
dom.insert_before(list_el, item, dom.query(".sentinel", list_el))
dom.remove(item)
dom.batch_append(list_el, [item])
dom.clear_pool("messages")

Available helpers:

• dom.append(parent, child)
• dom.prepend(parent, child)
• dom.insert_before(parent, child, reference)
• dom.remove(element)
• dom.batch_append(parent, children)
• dom.clear_pool(key=None)

Animations and icons

icon = dom.create_icon("<svg>...</svg>", class_name="icon")
dom.animate_in(icon, duration=200)
dom.animate_out(icon, duration=150)

Available helpers:

• dom.create_icon(svg_string, class_name="icon")
• dom.animate_in(element, **options)
• dom.animate_out(element, **options)

Third-party interop

Integrate third-party libraries in lifecycle hooks and always clean up in on_stop():

from sprag import Module, imports

class ChartModule(Module):
    def on_start(self):
        self.chart = imports.ChartLib.create(self.element)

    def on_stop(self):
        if self.chart:
            self.chart.destroy()

Lower-level Ragot helpers

If you need to drop below the dom.* helper surface, the shipped Ragot runtime also includes lower-level primitives such as createLazyLoader(...) and createInfiniteScroll(...). SPRAG's normal authoring path usually reaches those through ui.LazyImage, @infinite_scroll, and virtual-scroll integration, but they are part of the underlying runtime.