Files
plainleaf/website/API/widget.md
T
2026-06-22 10:18:07 +02:00

3.4 KiB

#api/space-lua

APIs to define widgets in SilverBullet, often used through Space Lua#Expressions.

Widget types

Markdown widgets

When setting a markdown key, or using the widget.markdown API, a markdown-based widget can be created.

Example:

function helloWorld(name)
  return widget.markdown("Hello world, *" .. name .. "*!")
end

Can be used as follows:

${helloWorld("Pete")}

DOM widgets

To render a custom HTML-based widget, use the API/dom elements passed as an argument to widget.html:

function marquee(text)
  return widget.html(dom.marquee {
    class = "my-marquee",
    onclick = function()
      editor.flashNotification "You clicked me"
    end,
    text
  })
end

We can combine this with some Space Style to style it:

.my-marquee {
  color: purple;
}

This can be used as follows: ${marquee "Finally, marqeeeeeee!"}

Sandboxed widgets

For widgets that need to run JavaScript, e.g. to drive a third-party rendering library, set a script key. The html and script then run together inside an isolated sandbox iframe, so the widget's scripts and styles can't interfere with the editor.

Inside the sandbox the script has access to:

  • syscall(name, ...args) — call any API (returns a promise), e.g. syscall("editor.navigate", "Some Page").
  • loadJsByUrl(url) — load an external classic script (returns a promise that resolves once loaded).
  • automatic height — the iframe sizes itself to its content.

The widget's markdown value (if set) is what the Copy button copies — handy for exposing a scripted widget's source. Sandboxed widgets render as a block.

function clock()
  return widget.sandbox {
    html = [[<div id="t"></div>]],
    markdown = "Not supported",
    script = [[
      var el = document.getElementById("t");
      setInterval(() => { el.innerText = new Date().toLocaleTimeString(); }, 1000);
    ]],
  }
end

${clock()}

API

widget.new(spec)

To render a widget, call widget.new with a spec table setting any of the following keys:

  • markdown: Renders the value as markdown. For html/script widgets it is not displayed but is used as the Copy button's content.
  • html: Renders a HTML DOM as a widget. It is usually used in conjunction with the API/dom API.
  • script: JavaScript to run alongside html inside a sandbox iframe (see #Sandboxed (scripted) widgets). When set, the widget renders in sandbox mode.
  • display: Render the value either inline or as a block (defaults to inline).
  • cssClasses: A list of CSS class names to set on the widget's wrapper element.

widget.markdown(text)

Shortcut for widget.new { markdown = text }

widget.html(htmlOrDOM)

Shortcut for widget.new { html = htmlOrDOM }

Usually used in conjunction with API/dom.

widget.htmlBlock(htmlOrDOM)

Shortcut for widget.new { html = htmlOrDOM, display = "block" }

Block-level version of widget.html.

widget.markdownBlock(text)

Shortcut for widget.new { markdown = text, display = "block" }

Block-level version of widget.markdown. Useful for content that needs to render as a block element (lists, tables, headings, etc.).

widget.sandbox(spec)

Convenience wrapper for a #Sandboxed widgets widget.

Keys:

  • html
  • script
  • markdown (Copy-button content)
  • cssClasses
  • display (defaults to block)