Single Panel Widget

Use the Single Panel widget to embed a chart, metric, or summary panel that has already been created in Qrvey Composer.

Note: Unlike Dashboards, Single Panel widgets do not include the full set of dashboard functionality such as global filters. When embedding a Single Panel widget, only the visualization itself is rendered.

Embeddable Sample

The following sample demonstrates how to embed a single panel in your system.

Important: This example is for testing purposes only.

• API Key: Do not expose your API key in production. Use it only for communication between back ends.
• Minimal Config: The sample uses the minimum set of properties needed for quick testing. Production deployments can require additional properties.

<an-panel config="singlePanelConfig"></an-panel>

<!-- Widget's Configuration Object -->
<script>
var singlePanelConfig = {
   "apiKey": "<YOUR_PRIVATE_API_KEY>",   // Testing only. Do not expose in production.
   "appId": "<APP_ID>",
   "domain": "https://<YOUR_QRVEY_DOMAIN>",
   "userId": "<USER_ID>",
   "qrveyId": "<DATASET_ID>",            // Represents the dataset ID
   "type": "CHART",                      // Can also be "METRIC" or "SUMMARY"
   "chartId": "<CHART_ID>"               // Use metricId if type=METRIC, summaryId if type=SUMMARY
}
</script>

<!-- Widget's Launchers -->
<script type="module" src="<WIDGETS_URL>/qrvey-an-widgets/an-dashboard/andashboard/andashboard.esm.js"></script>
<script nomodule src="<WIDGETS_URL>/qrvey-an-widgets/an-dashboard/andashboard/andashboard.js"></script>

Production Deployment

When deploying to production:

• Use a qvToken instead of an apiKey.
• Ensure appId, userId, and qrveyId are passed using a token, not hard-coded.
• clientId, orgId, and orgs are not required for rendering the widget but can be provided when you want the Single Panel widget to act as a gateway for other components (such as Download Manager, Export Data modal, Subscriptions, or personalization).
• Configure additional properties such as panel, featurePermission, and i18n as needed.
• Keep the API key securely stored on the server side only.

Configuration Object

Property	Type	Required	qvToken Support	Description
domain	string	Y	N	Qrvey instance URL. Example: https://example.qrvey.com.
qvToken	string	Yes if apiKey is not provided.	-	Encrypted token used for secure authentication. Used in production to securely pass all required parameters. Cannot be used with apiKey.
apiKey	string	Y (if qvToken is not provided)	N	Secret token for accessing the application. Caution: For testing only. Do not use in the production UI. Cannot be used with qvToken.
appId	string	Y	Y	ID of the Qrvey application that contains the chart, metric, or summary panel.
userId	string	Y (if not in session cookie)	Y	ID of the Qrvey Composer user that owns the application being embedded. Alternatively, it can be passed in a Qrvey session cookie.
qrveyId	string	Y	N	Represents the dataset ID to be used in the panel.
type	string	Y	N	Defines the panel type. Options: CHART, SUMMARY, or METRIC.
chartId	string	Yes if type is CHART	N	ID of the chart to display.
metricId	string	Yes if type is METRIC	N	ID of the metric to display.
summaryId	string	Yes if type is SUMMARY	N	ID of the summary panel to display.
clientId	string	N	Y	Not required for rendering. Unique identifier for the tenant end user. Used for personalization and passed to other components such as Download Manager or Export modal.
orgId	string	N	Y	Not required for rendering. ID of the organization to which the roles and users are assigned. To list the roles and users in the subscribe modal, this value should correspond to the user in the session orgId. For more information, see Exports.
orgs	Object array	N	Only	Not required for rendering. Defines users and roles grouped by organization. Used to enable sharing/subscription features in other components.
email	string	N (required for scheduling/subscriptions)	Only	Email of the clientId user. Enables scheduling of exports/subscriptions.
panel	object	N	N	Allows configuration of panel features (header, body, footer, styles, and so on). For more information, Panel Object.
menuLayout	object	N	N	Allows configuration of menu position in a chart panel. Options: hidden, header, floating (default: header). For more information, see floatingMenu.
userFilters	object	N	Y	Collection of custom filters applied to the panel visualization. For more information, see User Filters.
timezone	string	N	Y	Timezone offset applied to dates. For more information, see Configuring Time Zone Settings.
i18n	object	N	N	Defines language for UI text and dataset columns. Supports internationalization. For more information, see i18n Object.
themeId	string	N	N	Theme ID to apply a pre-defined theme. For more information, see Accessing a Theme Programmatically.
featurePermission	object	N	N	Enables you to create a customized view by showing and hiding specific features. For more information, see Feature Permission Object.
customTokens	object	N	N	Adds personalization with custom tooltips. For more information, see Custom Tokens Example: { "my_header": "Tooltip Header" }.

Exports

Local and scheduled exports created from this widget are associated with the clientId and orgId that control their display in the Download Manager widget.

If clientId and orgId are passed through a JWT to the widget, the same JWT is sent to the export requests and considered when creating the Download Manager records, even if the widget itself does not use these properties.

Orgs

For full details on how orgs work, see Organizations, Ownership, and Subscriptions.

Property	Type	Description
orgId	string	ID of the organization to which the roles and users are assigned. To list the roles and users in the subscribe modal, this value should correspond to the user in the session orgId
users	array	An object/array of users to be listed in the subscribe modal. This is not for the current user. Adjust clientId and email accordingly.
users.clientId	string	Client ID of the user.
users.email	string	Email address of the user.

Example

const orgs = [
  {
    orgId: "ORG_ID",
    users: [
      {
        clientId: "CLIENT_ID",
        email: "EMAIL"
      },
      {
        clientId: "CLIENT_ID2",
        email: "EMAIL2"
      }
    ]
  }
];

i18n

For more information, see Internationalization, Step by Step.

Property	Type	Required	Value
lang	string	Y	Language to use for the UI (examples: "es", "es-ES").
locale	string	N	Locale code to use for date and number formatting (for example, "es-ES").
currencyFormatOverride	string	N	Accepts currency codes and sets the currency (for example, "EUR") on visualizations and their exports. It overrides the default currency format in the application. Supports the list of ISO 4217 currency codes.

Note: Currency set directly on a column in a chart using the Values Format option supersedes the currency setting in currencyFormatOverride.

Example Configuration

var config = {  
  "domain": "<DOMAIN>",  
  "qvToken: "<QVTOKEN>",      
  "i18n": {
    "lang": "en",
    "locale": "EN",
    "currencyFormatOverride": "EUR"
  }
}

Note: The i18n object is supported only in the widget configuration object. It cannot be passed in a JWT.

Timezone

Property	Type	Required	Description
timezone.offset	string	N	Specifies the timezone offset. Accepted formats: +03:00, -03, and so on.

Panel

Property	Type	Required	Description
panel.header	object	N	Panel header options object.
panel.header.visible	Boolean	N	Determines if the panel header is visible. Defaults to true.
panel.header.draggable	Boolean	N	Used by Custom View and Metric View panels. If true, the panel header has an icon to drag and drop the panel. Defaults to false in embedded widgets.
panel.header.filter	Boolean	N	Determines if the panel header has a filter button to open the Filter Modal widget. Defaults to false in embedded widgets.
panel.header.menu	array/Boolean	N	If it's an array, the panel header displays the options passed through the array. If the value is true, the panel header displays a default menu. Accepted values for the array: EDIT, DOWNLOAD, DUPLICATE, SIZE and DELETE. Note: SIZE is used only by Custom View panels.
panel.header.fit_panel	Boolean	N	Set to true if "fit to panel" button is enabled (false by default).
panel.header.title_prefix	string	N	Sets a prefix for the title of the panel.
panel.header.chartSelection	Boolean	N	Allow the user to change the chart type.
panel.header.columnAggregation	Boolean	N	Allow the user to select and change the columns aggregates directly from the self-service option.
panel.header.columnGrouping	Boolean	N	Allow the user to add or remove groups in a simple or grouped table.
panel.header.columnReplacement	Boolean	N	Allow the user to select and change the columns as the self-service option.
panel.header.columnSection	Boolean	N	Allow the user to add or remove sections in an expandable table.
panel.header.columnSelection	Boolean	N	Allow the user to add or remove columns in table charts.
panel.header.dateGrouping	object	N	Allow the user to change date grouping. These items are accessible under the Column settings icon.
panel.header.externalDownload	array	N	Set of values to allow external download for defined formats. Used by the Dashboard. Accepted Values: CSV.
panel.header.sorting	Boolean	N	Determines if sorting button is shown in the panel header.
panel.header.smartAnalyzer	Boolean	N	Allow the user to access the Smart Analyzer icon from a chart header. Defaults to true when the Smart Analyzer AI Agent is enabled in the Admin Center.
panel.body	object	N	Panel body options object.
panel.body.popup	object	N	Panel body popup options object. Used to show Filter By, See Data, and Drill-Down options.
panel.body.popup.items	array	N	Set of options to show on the popup. For more information, see panel.body.popup.items properties.
panel.body.popup.items[itemIndex]	object	N	Popup item options object to use in panel.body.popup.items array.
panel.body.popup.items[itemIndex].label	string	N	Option name. Required for this array.
panel.body.popup.items[itemIndex].action	Function	N	Custom callback function.
panel.body.comparativeAnalysis	Boolean	N	Allow the user to perform Comparative Analysis. Cannot be enabled in the widget if it is disabled in the chart configuration.
panel.floatingMenu	object	N	Controls the display of icons in a floating menu.
panel.floatingMenu.smartAnalyzer	Boolean	N	Allow the user to access the Smart Analyzer from a floating menu. Defaults to true when the Smart Analyzer AI Agent is enabled in the Admin Center.
panel.footer	object	N	Panel footer options object.
panel.footer.visible	Boolean	N	Determines if a panel footer is visible. Defaults to false.
panel.styles	object	N	Styles options object. These properties extend the current theme.
panel.styles.chartsTitle	string	N	Set the charts title color using a hex value.
panel.styles.chartsFontFamily	string	N	Set the charts font family.
panel.styles.axisDataLabels	string	N	Set axis labels color in charts.
panel.styles.dataLabels	string	N	Sets a hexadecimal color for data labels in charts.
panel.styles.valuesMain	string	N	Sets a hexadecimal color for axis ticks values in charts.
panel.styles.chartsLegends	string	N	Sets a hexadecimal color for charts legends labels.
panel.styles.chartsTooltips	string	N	Set a hexadecimal color for charts tooltips.
panel.styles.tableHeaderFont	string	N	Sets color for table header texts.
panel.styles.chartsMain	string	N	Sets color for chart data points like bars, symbols and lines.
panel.styles.themePalette	array	N	Sets up to 20 hexadecimal color values for chart data points like bars, symbols, and lines.

dateGrouping

// example
"dateGrouping": {
  "year": true,
  "quarter": true,
  "month": true,
  "week": true,
  "quarter_only": true,
  "month_only": true,
  "day_only": true,
  "advancedGrouping": {
    "day": true,
    "hour": true,
    "minute": true,
    "second": true,
    "hour_only": true,
    "minute_only": true,
    "second_only": true
  }
}

floatingMenu

"panel": {
  "menuLayout": "floating", // "hidden" | "header" | "floating"
  "header": {
      "menu": ["EDIT","SIZE"],
  },
  "floatingMenu": {
    "edit": false,
    "duplicate": false,
    "delete": false,
    "download": {
      "jpg": false,
      "pdf": true,
      "excel": false,
      "csv": false,
      "csv-summary": true
      },
    "columnGrouping": true,
    "columnSelection": true,
    "columnSection": true
    },
   }

panel.body.popup.items

Accepted array items format:

let item = {
  label: '<popup_item>',              // Required
  action: customCallbackFunction(),   // Optional
  customdrills: <Array>               // Optional
}

Example: [{ label: 'SEEDATA' }, { label: 'FILTERBY' }, { label: 'DRILLDOWN' }, { label: 'CUSTOMDRILL' }]

Feature Permission

Property	Type	Required	Description
downloads	object	N	Hide the Export feature, which supports exporting charts, tables, dashboards, and reports to downloadable files (PDF, JPG, CSV, EXCEL, CSV SUMMARY). For single panel, contains hideSchedule.
downloads.hideSchedule	Boolean	N	If true, hide the Schedule option in the Export feature (default: false).
featurePermission.hideSubscription	Boolean	N	Hide the subscription option in the export modal.
featurePermission.hideSubscribeExternalUsers	Boolean	N	Disable the option of subscribing users outside of the organization.

Styles

The Single Panel Widget supports customization through CSS variables, allowing you to adapt the look and feel of dashboards to match your application’s design system. This includes control over fonts, colors, spacing, and other UI elements.

By overriding the available style variables, you can achieve a fully branded experience for end users without altering functionality. This is recommended to ensure consistency across embedded dashboards.

For the complete list of available style variables and examples of how to use them, see Customize Widgets Using CSS.