Customize Widget Styles
By customizing the appearance of a Qrvey widget in your application, you can provide a more native presentation within your product.
Overview
Qrvey widgets use web components and the shadow DOM rather than iframes. The rendered widget contains many internal elements and classes that are not visible in the host page until the widget is rendered. Because the internal DOM can change, it adds a risk factor when relying on direct class or element selectors to style internal elements.
The only HTML markup that you see for a Qrvey widget is a custom HTML tag. To provide safer, more flexible theming without coupling to internal markup, Qrvey exposes a set of CSS variables. You can define these variables in your application stylesheet, allowing the widget to read them from the host page. They provide clear control over UI elements like fonts, borders, padding, and popup positioning while preserving the flexibility of web components and the shadow DOM.
To customize charts, see the Customize Chart Styles tutorial.
Widget Style Customization Tutorial
The following tutorial video shows how to use custom styles with special CSS classes to customize the look and feel of widgets. It focuses on a dashboard widget, but the concepts apply to all embedded Qrvey widgets.
Tags: Widgets, Customizations, CSS
Naming Convention for Qrvey CSS Variables
To ensure consistency, each Qrvey CSS variable uses the following naming convention:
--qv-<module>-<property>-<attribute>
- Starts with two dashes.
- Begins with QV- (Q and V followed by a dash).
- Includes a module name when applicable.
- Includes a property and typically an attribute for context.
Examples of modules include dashboard, chart, and global. The following example defines the color for text used in a dashboard:
--qv-dashboard-color-text: orange;
Properties can include color, font, border, or padding. Attributes give further context such as title, text, or tooltip.
CSS Variable Catalog
Qrvey publishes a reference of variables that you can use. Typical categories include the following:
- Colors for titles, text, icons, and backgrounds.
- Fonts to set the typeface used across widget components.
- Positioning for popups and toast notifications.
- Borders including radius and border color.
- Paddings and spacing for panels and controls.
Note: Chart-specific styles such as axis fonts, data label colors, and series colors are controlled by themes rather than CSS variables. Use the provided CSS variables to customize widget UI controls, such as dashboard panels. Use the built-in Style Themes to customize styles for charts and metrics.
Variable Definition Location
Define your Qrvey CSS variables in the same location as your core application classes. You can attach variables to a container element that wraps the widget or define them globally depending on your scope preferences. Common approaches include the following:
- Wrap the widget in a container and attach variables to that container (example selector:
.widget-container). - Attach variables directly to the widget element. For a dashboard widget, the element is
qrvey-dashboard.
Example
To change all of the fonts used in a dashboard widget to cursive, you can define a font family variable in the <div> container in the front-end code that embeds the widget.
-
Add a custom style element block (ID selector class) to the
<head>of your widget's.htmlfile.<style>
#widget container {
-- qv-global-font-family; cursive;
}
</style>If your HTML file doesn't contain a
<div>block, you can add an element selector class to the style entry.<style>
#widget container qrvey-dashboard {
-- qv-global-font-family; cursive;
}
</style> -
Set the variable on
.widget-containerorqrvey-dashboardin your stylesheet to make it available when the widget renders.
To test your style changes, you can refresh the browser display for your dashboard. Only fonts in the dashboard widget change to cursive, while application fonts remain the same.
Additional Style Examples
To adjust panel title size and weight, use the dashboard panel title variables to increase font size and make titles bold.
<style>
#widget container {
-- qv-an-font-size-chart-panel-title: 30px;
-- qv-an-font-weight-chart-panel-title: bold;
-- qv-an-font-size-chart-panel-options: 20px;}
</style>
To round panel borders and add padding, you can modify border radius variables.
<style>
#widget container {
-- qv-global-border-radius: 20px;
-- qv-an-font-size-chart-panel-title: 30px;
-- qv-an-font-weight-chart-panel-title: bold;
-- qv-an-font-size-chart-panel-options: 20px;}
</style>
These affect the title and icon text within each panel but not the chart content itself. To change chart content, use themes.
To add spacing inside panels, use padding variables.
<style>
#widget container {
-- qv-an-padding-chart-panel-header: 15px;
}
</style>
Checklist
- Bookmark the Qrvey CSS variables reference for available variable names and examples.
- Determine scope (global or container-specific).
- Define variables in the same location as your core application CSS classes.
- Use themes for chart styles.
- Refresh and inspect the rendered widget to confirm appearance.
Best Practices
- Scope variables when possible. If a particular widget on a page needs a different look, attach variables to a wrapper element instead of globally.
- Use themes for charts when you need to change bar colors, pie wedge sequences, axis fonts, or data label styles.
- Test after rendering. Because widgets render their internal DOM at runtime, validate changes in the browser after the widget has initialized.
- Avoid targeting internal classes. Internal markup and class names can change. Relying on published CSS variables is stable and forward-compatible.