Skip to main content
Version: 9.2

Customize Widget Styles

By customizing the appearance of a Qrvey widgets 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.

For fine-grained chart styling, you can combine this approach with Qrvey themes. With variables for widget chrome and themes for chart internals, you can create a cohesive, polished user experience.

Widget Style Customimzation 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 dashboard widgets, 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. 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:

  • 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 widget CSS variables for UI Chrome and panel-level styling. Use themes for chart internals.

Variable Definition Location​

Add your variable definitions to your application stylesheet so they load with your core styles. 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 curve-dashboard.

Example​

The following general workflow shows how a style changes affect the UI.

  1. Change all widget fonts.

    • Define a font family variable on the container. The widget uses this for component UI elements, not for chart text.
    • Set the variable on .widget-container or curve-dashboard in your stylesheet so it is available when the widget renders.

  2. Adjust panel title size and weight.

    Use the dashboard or panel title variables to increase font size and make titles bold. These affect the title and icon text within each panel but not the chart content itself.

  3. Round panel borders and add padding.

    • Modify border radius variables to create more rounded panels.
    • Use padding variables to add spacing inside panels so controls and titles do not touch the edges.

  4. Adjust control sizes.

There are variables for control and option sizing. Increase these if UI elements feel too small on your layout.

Quick checklist​

  • Bookmark the Qrvey CSS variables reference for available variable names and examples.
  • Determine scope (global or container-specific).
  • Define variables in your application stylesheet or component styles.
  • Use themes for chart internals.
  • Refresh and inspect the rendered widget to confirm appearance.

Best Practices​

  • Store variables in your main stylesheet. That ensures styles apply consistently across pages that include the widget.
  • 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. To change bar colors, pie wedge sequences, axis fonts, or data label styles, create or select a theme rather than use CSS variables.
  • 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.