4.2 Using Labels Effectively
      Back to home
      1. Home
      2. 4: Data Tables & Labels
      3. 4.2 Using Labels Effectively

      Controlling Widget Display Using Labels

      How to use label configurations in Rayven to manage the number and grouping of widgets shown on your app interfaces.

      Overview

      In Rayven, widgets are the visual elements that appear on your application's interfaces and present data to users. The way widgets are displayed—especially how many appear and how they're grouped—can be controlled using labels configured in your Primary Table.

      This feature is particularly useful for applications where the same widget needs to show data for multiple entities, such as customer groups, locations, or product categories. This article explains how to use label-based settings to control widget display on interfaces.

      Widget Display Options via Label Settings

      Every Frontend node in Rayven includes a setting called “Number of Widgets to Display”. This setting determines how many instances (or “copies”) of the widget will be shown on an interface and how they are grouped.

      Where to Configure

      This setting is applied inside the Frontend node configuration, within your workflow. When the node is later added to an interface, it will behave according to this configuration.

      Available Display Options

      There are three available modes to control how many widgets appear for each Frontend node:

      1. One Widget per Label

      This is the default configuration and is suitable for most applications. It simply displays one widget for the selected Frontend node, without splitting it into separate widgets for each row or label value.

      You can think of it as showing a general summary or result across your dataset—or whatever data has been grouped and calculated in the workflow behind the node.

      In many use cases, you won’t need to change this setting. It’s designed to give you a clean, high-level view that works out of the box.

      Example:
      If your workflow calculates the total number of active jobs across all customers, this setting will show a single value in one widget.

      2. One Widget per Label Value

      Use this option when you want to break out your data by group, showing a separate widget for each value in a chosen label column.

      It’s ideal when you need side-by-side comparisons across categories like customer types, teams, or regions—especially when those groups are meaningful to your users.

      Example:
      If your Primary Table has a label called Customer Type with values like "Retail", "Industrial", and "Finance", this setting will display three widgets—one for each customer type.

      3. One Widget per UID

      This option creates one widget for every individual row in your Primary Table. It’s best for applications where each entity—such as a customer, asset, or device—needs its own dedicated view.

      It gives the most granular breakdown, but should be used carefully, as displaying too many widgets can affect interface performance or overwhelm users.

      Example:

      If your Primary Table includes 20 temperature sensors, this setting will create 20 widgets—each one showing the current reading from a specific device.

      Just keep in mind: if your table has hundreds of rows, the interface may become cluttered or slow to load, so use this mode with care.

      How It Works Behind the Scenes

      The grouping is determined by labels set on your Primary Table. These labels define how rows are grouped and filtered.

      • Labels can be configured as:

        • Default (No Label) – no grouping.

        • Single Label – one grouping per row.

        • Multi-Label – rows can belong to multiple groups.

      To make use of label-based widget grouping:

      1. Add a label column to your Primary Table.

      2. Populate that column with label values (e.g., region, type, status).

      3. Set the Frontend node’s "Number of Widgets to Display" setting to use that label.

      4. Add the Frontend node to your interface.

      When to Use Which Setting

      Setting When to Use It
      One Widget per Label (default) When you want a single view that summarises or represents the full dataset. Ideal for most interfaces or overview pages.
      One Widget per Label Value When you want to compare values or display data across groups (e.g. by region, customer type, or category).
      One Widget per UID When each individual item (e.g. device, customer, asset) needs its own dedicated widget.
       

      Best Practices

      • Use the simplest grouping that makes sense: Start with "One Widget per Label" if a single summary or view is enough. Move to per-label-value or per-UID only when there's a clear need to break the data out.

      • Consider performance and usability: "One Widget per UID" can create a widget for every record—fine for small datasets, but avoid it for large tables unless users genuinely need that level of detail.

      • Tailor visibility with User Groups and Labels: Combine label-based widget display with User Group label filters to ensure each user sees only the data relevant to them.

      • Label intuitively: Use clear, descriptive label names (e.g. “Region”, “Team”, “Project”) so the interface stays readable and user-friendly.

      • Avoid overcrowding: Too many widgets on one interface can overwhelm users. Use multiple interfaces or drilldowns when the data warrants it.

      Summary

      Rayven provides fine-grained control over how widgets are displayed by allowing you to group them based on labels in your Primary Table. Using the “Number of Widgets to Display” setting within each Frontend node, you can tailor your interface to display one widget per UID, per label value, or per label. This allows for both high-level overviews and detailed entity-level visualisations—all from the same node.

      FAQs

      What’s the default widget display setting?
      "One Widget per Label" is the default setting on all Frontend nodes.

      Do I need to use labels for widgets to work?
      No. You can use the default "Primary Label = All" setup if you don’t need grouping. However, labels unlock powerful grouping options.

      Can I use multiple labels to control widget display?
      No. Each Frontend node supports grouping by a single label. However, you can configure different Frontend nodes to group by different labels.

      What if I change the label values after building my interface?
      f your Frontend node is set to “One Widget per Label Value”, the widgets will update based on the current label values in your Primary Table.
      This can lead to unintended effects—widgets may move, disappear, or appear in new positions if label values are changed, removed, or reassigned. Always review your interface layout after modifying label values to ensure everything still appears as intended.

      What if I add or remove UIDs in the Primary Table?
      If your Frontend node is set to “One Widget per UID”, widgets will be added or removed to reflect the current list of UIDs in the Primary Table.
      This can impact interface layout and spacing, especially when many records are added or removed at once. Consider using label-based grouping if you want more stable widget counts.

      Can I mix display settings across widgets?
      Yes. Each Frontend node can have its own “Number of Widgets to Display” setting, so you can mix per-label, per-value, and per-UID widgets across a single interface.

      What if I want different users to see different widgets?
      Use User Groups with Label Filters to limit data access. This works in conjunction with label-based widget display settings to personalise the interface.