# Styling with CSS

## Overview

Ubidots now supports **Custom CSS Stylesheets**, allowing you to directly access and modify the CSS of your application and its login page. This feature provides greater flexibility to adapt the visual appearance of your solutions beyond the default configuration options.

By applying your own CSS rules, you can:

* **Customize styles** such as fonts, colors, and visualization details to better suit your design requirements.
* **Reinforce brand identity** by aligning the Application and login page with your organization’s branding guidelines.
* **Enhance user experience** by tailoring the interface to your users’ needs.

This feature is intended for users who need more control over the presentation of their Applications, ensuring both the dashboards and the login page deliver a consistent, branded experience.

{% hint style="success" %}

* The App's custom CSS  and Login CSS is only available in the [Enterprise tiers](https://ubidots.com/pricing).
* This is an advanced customization feature that requires extensive CSS knowledge. If you need help customizing your Application and Login CSS, contact us at <support@ubidots.com>.
  {% endhint %}

{% hint style="warning" %}

* Login page CSS will be released soon. Be attentive to our newsletter or product updates email.
* Any CSS class beyond the public API isn't actively maintained. We don't recommend targeting unsupported classes or HTML elements. If you find that there's a lack of coverage, please contact us at <support@ubidots.com>.
  {% endhint %}

Styling with CSS can take your application from this:

{% columns %}
{% column %}
**Login page**

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FIDuo2pvP3CXDI6Flq1g2%2FNormal%20login.png?alt=media&#x26;token=c0841998-8714-4632-bd8a-3268a460ecb9" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}
**Application**

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2F7SAqbhC6UGXgJNZHWJNm%2FSimple%20branded%20native%20app.png?alt=media&#x26;token=a0920617-dd5f-4d47-92ca-495ba09c2a62" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

To this:

{% columns %}
{% column %}
**Login page**

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FNJCq6cRGYePIBan50Bws%2FCustom%20CSS%20Login.png?alt=media&#x26;token=7c128b3f-02ff-4c35-9d09-5fdbc5f5825c" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}
**Application**

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FhzZRieHZ6TxfQwpoKBM4%2FBranded%20CSS%20native%20app.png?alt=media&#x26;token=080b668b-1f26-4b2c-8a9e-01cf1b711555" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

## BEM notation

BEM (Block Element Modifier) is a CSS naming methodology for classes that helps create reusable and maintainable stylesheets. Our design system, VulcanUI, implements a strict BEM convention with the `ds-` prefix for all component classes.

### BEM structure <a href="#bem-structure" id="bem-structure"></a>

Ubidots' BEM naming convention follows this pattern:

```
ds-block__element--modifier
```

Where:

* **`ds-`** Required prefix for all VulcanUI design system classes.
* **`block`** - The component name (e.g., `Sidebar`, `Table`, `NavBar` or `Accordeon`).
* **`__element`** - Optional component part (e.g., `__container`, `__wrapper`, `__cell`).
* **`--modifier`** - Optional state or variant (e.g., `--primary`, `--disabled`, `--active`).

### Key rules <a href="#key-rules" id="key-rules"></a>

Ubidots BEM notation system implements key rules for the classes:

1. **Maximum 2-level nesting**: Uses `block__element`, never `block__element__subelement`
2. **Semantic hierarchy**: Elements must be logically positioned under their parent.
3. **Lowercase only**: All class names must be lowercase with hyphens.
4. **Consistent separators**: Always uses `__` for elements and `--` for modifiers.

### Class examples

Below are a few examples of classes from BEM-supported components within the application, but you can find the full list in the respective [component sections](https://dev.ubidots.com/apps/styling-with-css/application-css).

{% tabs %}
{% tab title="Table" %}

#### **Classes**

The below classes target specific HTML `<div>` tags within the Table component.

1. `ds-table__viewport`
2. `ds-table__toolbar`
3. `ds-table__wrapper`
4. `ds-table__controls`

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FU39cPiGWGjXytJOD5aKL%2FTable%20outer%20classes.png?alt=media&#x26;token=35614248-9608-44c7-beb8-574ae05ab473" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Sidebar" %}

#### **Classes**

The below classes target specific HTML `<div>` tags within the application Sidebar.

1. `ds-sidebar__viewport`
2. `ds-sidebar__header`
3. `ds-sidebar__body`
4. `ds-sidebar__footer-wrapper`

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FHQDFHML44HyMtnKKeAQG%2FSidebar%20outer%20classes%20(styling%20section).png?alt=media&#x26;token=26e47a8f-7b91-4574-8f9a-cf06b344b825" alt="" width="283"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="NavBar" %}

#### **Classes**

The below classes target specific HTML `<div>` tags within the application NavBar.

1. `ds-navbar`
2. `ds-navbar__wrapper`
3. `ds-navbar__logo`
4. `ds-navbar__options`&#x20;
   {% endtab %}

{% tab title="Accordeon" %}

#### **Classes**

The below classes target specific HTML `<div>` tags within the Accordeon component.

1. `ds-accordion`
2. `ds-accordion__toggle`
3. `ds-accordion__content`
4. `ds-accordion__header`&#x20;
   {% endtab %}
   {% endtabs %}

## Core/Entity vs. Design System classes

Ubidots implements two distinct CSS class systems that serve different purposes within the platform. Understanding the difference between these systems is crucial for proper styling and customization.

### Design System Classes <a href="#design-system-classes-ds-prefix" id="design-system-classes-ds-prefix"></a>

Design system classes are component-level styles that follow strict BEM notation and are prefixed with `ds-`. These classes are managed by the VulcanUI design system and provide consistent styling for reusable UI components.

**Characteristics:**

* **Prefix**: Always start with `ds-`.
* **Scope**: Individual UI components (buttons, tables, inputs, etc.).
* **Naming**: Follow BEM convention (`ds-block__element--modifier`).
* **Purpose**: Ensure visual consistency across components.

Examples [here](#class-examples).

### Core/Entity Classes <a href="#coremodule-classes-application-level" id="coremodule-classes-application-level"></a>

Core and entity classes are application-level containers that provide structure for entire views and sections within the Ubidots platform. These classes enable entity-specific customization while maintaining global consistency.

**Characteristics:**

* **Prefix**: Entity name or `core-`.
* **Scope**: Page layouts and view containers.
* **Naming**: `<`entity`>-view__container` pattern, or `core-view__container` class
* **Purpose**: Enable view-level customization and theming.
* **Structure**: Hierarchical container system

{% tabs %}
{% tab title="Global Core Classes" %}
Every view in the Ubidots application includes the global core class:

```html
<div class="core-view__container">
  <!-- All view content -->
</div>
```

{% endtab %}

{% tab title="Entity-Specific Classes" %}
Each entity has its own container class following the pattern `<`Entity`>-view__container`:

```html
<div class="core-view__container">
  <div class="devices-view__container">
    <!-- Devices entity content -->
  </div>
</div>
```

**Common entity examples:**

* `devices-view__container`
* `dashboards-view__container`
* `reports-view__container`
* `events-view__container`

For a complete list of Core/Entity classes, see [here](#coremodule-classes-application-level).
{% endtab %}
{% endtabs %}

### Implementation Structure <a href="#implementation-structure" id="implementation-structure"></a>

The final HTML structure within an application combines both class systems:

```html
<!-- Application-level containers -->
<div class="core-view__container">
  <div class="devices-view__container">
    
    <!-- Design system components -->
    <div class="ds-table__viewport">
      <table class="ds-table">
        <thead class="ds-table__head">
          <tr class="ds-table__row">
            <th class="ds-table__cell ds-table__cell--sortable">
              Device Name
            </th>
          </tr>
        </thead>
      </table>
    </div>
    
  </div>
</div>
```

### When to Use Each System <a href="#when-to-use-each-system" id="when-to-use-each-system"></a>

#### Use Design System Classes (`ds-`) for: <a href="#use-design-system-classes-ds-for" id="use-design-system-classes-ds-for"></a>

* Styling individual UI components
* Ensuring visual consistency
* Component-specific states and variants
* Reusable interface elements

#### Use Core/Entity Classes for: <a href="#use-coremodule-classes-for" id="use-coremodule-classes-for"></a>

* Page-level layout customization
* Entity-specific theming
* View container styling
* Application-wide structural changes
* Custom CSS overrides for specific sections

### Customization Guidelines <a href="#customization-guidelines" id="customization-guidelines"></a>

**For Design System Components:**

```css
/* Customize component variants */
.ds-table__viewport {
  background-color: var(--custom-primary);
}
```

**For Application Views:**

```css
/* Global view customization */
.core-view__container {
  max-width: 1200px;
  margin: 0 auto;
}

/* Entity-specific customization */
.devices-view__container {
  background-color: var(--devices-bg);
  padding: 2rem;
}

/* Target design system components within specific entities */
.devices-view__container .ds-table {
  border-radius: 8px;
}
```

This dual-class system ensures both component consistency through the design system and application flexibility through core/entity classes.

## Branding colors

Accessing the [colors palette](https://help.ubidots.com/en/articles/830962-application-branding-how-to-customize-your-ubidots-user-interface) of the app is possible from the CSS stylesheets of both the application and the login page. This is useful if you want to define reusable CSS variables that inherit from those colors.&#x20;

To do so, use the the `{{colors.<colorKey>}}` bookmark syntax within the CSS stylesheet.

### Color keys

Some keys are self-explanatory by matching the color name shown in the App's branding section. Others have the respective name so you can identify them.

{% columns %}
{% column width="41.66666666666667%" %}

* `iconColor` - Icons
* `navbarColor` - Primary Navigation
* `variablesIcon`&#x20;
* `loginFormColor` - Login Background
* `subHeaderColor` - Secondary Navigation
* `widgetBackground`&#x20;
* `widgetTitleColor`&#x20;
* `dangerButtonColor`&#x20;
* `defaultButtonColor` - Primary button
* `mainTableItemColor`&#x20;
* `subHeaderTextColor` – Navigation text
* `dashboardBackground`&#x20;
* `loginButtonFormColor`&#x20;
* `warningModalCoverColor` - Warning
* `variableInfoboxCoverColor`&#x20;
* `informationModalCoverColor`&#x20;
* `loginFooterForegroundColor`&#x20;
* `dataSourceInfoboxCoverColor`&#x20;
* `variableInfoboxDerivedColor`&#x20;
  {% endcolumn %}

{% column width="58.33333333333333%" %}

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FEaH4GmoBW0TDNXRq2Xx1%2FColor%20palette.png?alt=media&#x26;token=ec73422f-4f1f-4703-a706-17094281e13c" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

### Example

This an example of using the branding colors palette as CSS reusable variables within the CSS stylesheet

```css
:root {
  --color-icon-color: {{ colors.iconColor }};
  --color-navbar-color: {{ colors.navbarColor }};
  --color-variables-icon: {{ colors.variablesIcon }};
  --color-login-form-color: {{ colors.loginFormColor }};
  --color-sub-header-color: {{ colors.subHeaderColor }};
  --color-widget-background: {{ colors.widgetBackground }};
  --color-widget-title-color: {{ colors.widgetTitleColor }};
  --color-danger-button-color: {{ colors.dangerButtonColor }};
  --color-default-button-color: {{ colors.defaultButtonColor }};
  --color-main-table-item-color: {{ colors.mainTableItemColor }};
  --color-sub-header-text-color: {{ colors.subHeaderTextColor }};
  --color-dashboard-background: {{ colors.dashboardBackground }};
  --color-login-button-form-color: {{ colors.loginButtonFormColor }};
  --color-warning-modal-cover-color: {{ colors.warningModalCoverColor }};
  --color-variable-infobox-cover-color: {{ colors.variableInfoboxCoverColor }};
  --color-information-modal-cover-color: {{ colors.informationModalCoverColor }};
  --color-login-footer-foreground-color: {{ colors.loginFooterForegroundColor }};
  --color-data-source-infobox-cover-color: {{ colors.dataSourceInfoboxCoverColor }};
  --color-variable-infobox-derived-color: {{ colors.variableInfoboxDerivedColor }};
}

.ds-table__viewport {
  background-color: var(--color-navbar-color);
}

```

## Custom fonts

Changing the font of the whole application and login page is doable with the Custom Font option in the Branding section:

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FOnHRH6joFl7gE59EdAze%2FCustom%20Fonts.png?alt=media&#x26;token=fa3c83a8-eee8-4624-af58-18225e12659e" alt=""><figcaption></figcaption></figure>

When clicking it, a modal opens where you can enter your fonts' URL, usually from [Google Fonts](https://fonts.google.com/) or other providers:

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2F7mpyEambPGJQX1UstFXi%2FCustom%20fonts%20modal.png?alt=media&#x26;token=9f43395f-1032-4c1f-88e1-930c41497230" alt=""><figcaption></figcaption></figure>

Once you import the font, you can use it in your application and login page's CSS as follows:

```css
:root {
    --font-family-primary: "Orbitron", "Inter";
}

/* ==========================================================================
   Apply custom font globally
   ========================================================================== */
*:not([role="icon"]) {
    font-family: var(--font-family-primary);
}
```

The result is:

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FvCKZEtRdpHcOpoqqXL1M%2FApplied%20custom%20font.png?alt=media&#x26;token=eb7089b7-be74-4453-bfac-c27df51f5466" alt=""><figcaption></figcaption></figure>