Nesting and reuse

Nesting and reuse

Referencing a local widget

<Widget.Using Name="WeatherCard" As="Weather" />

• Name must exactly match the Widget Name in the custom widget list.
• Duplicate names count as ambiguous and are flagged in the editor; a missing widget shows an error placeholder.
• As is the alias inside the current widget and must be unique among siblings; when omitted it is derived from Name.

Referencing a remote widget

<Widget.Using Url="https://example.com/weather.qwidget" As="Weather" />

• The URL must be https:443 and goes through the launcher backend proxy.
• It is fetched and validated on first reference; afterwards it updates silently on a 6-hour TTL.
• The data domains of remote widgets must be confirmed in the parent widget’s editor.

Text shorthand

<Widget.Using As="Weather">WeatherCard</Widget.Using>
<Widget.Using As="Weather">https://example.com/weather.qwidget</Widget.Using>

Passing initial input

<Widget.Using Name="WeatherCard" As="Weather">
  <Widget.Using.Arguments><![CDATA[{"city":"{Inputs.City}"}]]></Widget.Using.Arguments>
</Widget.Using>

Reading child state

<Text Value="{Children.Weather.Data.Temp}" Size="Lg" />

Dependencies and export

• Export only writes the current .qwidget; local dependencies are not inlined.
• The information panel lists the status of local dependencies: resolved / missing locally / duplicate name / remote.
• If a local dependency is missing at export time, you are prompted to distribute those widgets separately.
• To share a complete page, export the dependencies one by one, or reference everything by Url.

Cycles and depth

• Maximum depth is 5 levels.
• Self references and A→B→A cycles are detected; once found, an error placeholder is shown and the rest of the parent widget still works.
• At most 20 nested instances per parent widget.

Lifecycle

• A child widget has its own Inputs / Data / Results / Triggers / script sandbox.
• When a child unmounts, its timers, script sandbox and Blob URLs are cleaned up with it.
• Referencing the same local widget twice shares the data cache, but inputs and function results stay independent.

Example: reusable status card

<!-- StatusCard widget -->
<Widget Name="StatusCard" Version="1.0.0">
  <Container Padding="3" Gap="1">
    <Text Value="{Data.Title}" Weight="Semibold" />
    <Text Value="{Data.Value}" Size="2Xl" />
  </Container>
  <Data Name="Data" Type="Json" Url="https://example.com/status.json" />
</Widget>

<!-- parent widget -->
<Widget Name="Home" Version="1.0.0">
  <Row Gap="2">
    <Widget.Using Name="StatusCard" As="Players" />
    <Widget.Using Name="StatusCard" As="Tps" />
  </Row>
</Widget>

Related

• Widget references and scope
• Widget.Using reference