Vanilla Framework

4.49.0 · active · verified Sun Apr 19

Vanilla Framework is an extensible CSS framework built by Canonical, utilizing Sass for its core architecture. It provides a comprehensive set of pre-designed components, utility classes, and a robust design system for building consistent web interfaces, particularly those aligned with the Ubuntu design language. The current stable version is 4.49.0, with a rapid release cadence typically seeing multiple minor versions released each month, delivering new features, enhancements, and bug fixes. Key differentiators include its strong integration with the Ubuntu ecosystem, its extensibility through Sass themes and variables, and a focus on accessibility and modern web patterns. It offers a solid foundation for projects requiring a polished and consistent user interface without starting from scratch, consumable either by hotlinking pre-compiled CSS or, more commonly, integrated into a project's Sass build pipeline.

Common errors

```
Error: Undefined variable: "$my-custom-color".
```
cause Attempting to use a custom Sass variable or override a Vanilla Framework variable before the framework's main Sass file has been imported or the variable is defined.

fix Ensure that your custom variables or overrides are placed *after* `@import 'vanilla-framework';` and *before* `@include vanilla;` to ensure proper cascading and definition order.
```
Error: Can't find stylesheet to import. @import "vanilla-framework";
```
cause The Sass compiler cannot locate the `vanilla-framework` package. This typically happens if `vanilla-framework` is not installed, or if the `node_modules` directory is not included in the Sass `load-path` configuration.

fix First, ensure `vanilla-framework` is installed (`npm install vanilla-framework` or `yarn add vanilla-framework`). Then, configure your Sass build command to include `node_modules` in its `load-path`, e.g., `sass --load-path=node_modules src:dist`.
```
Error: SassError: Expected a pseudo-class or pseudo-element, but got identifier "vanilla".
```
cause This error occurs when `@include vanilla;` is used incorrectly, often by attempting to use it as an `@import` statement or placing it in an invalid Sass context (e.g., outside of a style block or before its definition is available).

fix Verify that `@include vanilla;` is used as a mixin call and is placed *after* the `@import 'vanilla-framework';` statement within your main Sass file.
```
ModuleParseError: Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type.
```
cause Attempting to directly `import` a Sass (`.scss`) file (e.g., `import 'vanilla-framework/scss/vanilla-framework.scss';`) into a JavaScript/TypeScript file without a configured Sass loader (like `sass-loader` for Webpack).

fix Either import the pre-compiled CSS file (`import 'vanilla-framework/dist/vanilla.css';`) if you don't need Sass customization, or configure your module bundler with an appropriate Sass loader (e.g., `sass-loader` for Webpack) to process `.scss` files.

Warnings

breaking Minor versions (e.g., v4.4x.0) often introduce new components and patterns (e.g., 'in-page navigation component', 'Tab section pattern'). While not explicitly labeled 'breaking', these updates might involve changes to underlying class names, Sass variables, or required markup structures that could inadvertently break existing layouts or customizations if not carefully reviewed during upgrades.
Fix: Always review the release notes and documentation before upgrading minor versions. Test your application thoroughly against the new version, especially in areas using components that have received updates.
gotcha Using an incompatible version of `sass` (e.g., older than `^1.79.0`) can lead to compilation errors, unexpected output, or `Undefined variable` errors due to syntax changes or removed features in the Sass language itself that Vanilla Framework relies on.
Fix: Ensure your project's `sass` dependency meets or exceeds the peer dependency requirement specified in `package.json` (`^1.79.0`). Upgrade `sass` using `npm install sass@latest` or `yarn add sass@latest`.
gotcha While hotlinking to specific versioned CSS files (e.g., `vanilla_framework_version_x_x_x_min.css`) is possible, it prevents automatic updates. This means you will not receive new features, bug fixes, or critical security patches unless you manually update the version in your HTML, leading to potentially outdated UIs and missed improvements.
Fix: For production applications, it's recommended to install Vanilla Framework via NPM/Yarn and integrate it into your project's build pipeline. This allows for controlled updates and leveraging Sass for customization.
gotcha Directly modifying compiled CSS or relying on internal, undocumented class names/structures for extensive customization is fragile. Such customizations are highly susceptible to breaking with framework updates, as internal implementation details can change without notice.
Fix: Prioritize customization through Sass variables, mixins, and provided extension points. When overriding, use the official documentation for component structure and only target stable, documented class names or patterns. Create your own Sass partials that import and extend Vanilla's styles.

Install

npm install vanilla-framework npm
yarn add vanilla-framework yarn
pnpm add vanilla-framework pnpm

Imports

vanilla-framework
wrong:
```
@import 'node_modules/vanilla-framework/scss/vanilla-framework';
```
correct:
```
@import 'vanilla-framework';
```
This Sass statement imports the framework's main Sass entry point. It requires your Sass compiler to have `node_modules` included in its `load-path` (e.g., `sass --load-path=node_modules src:dist`).
vanilla
wrong:
```
@import 'vanilla';
```
correct:
```
@include vanilla;
```
This Sass mixin is responsible for compiling and outputting the entire framework's CSS. It must be called within a Sass file *after* `@import 'vanilla-framework';` to have access to the mixin definition.
vanilla.css
wrong:
```
import 'vanilla-framework/vanilla.css';
```
correct:
```
import 'vanilla-framework/dist/vanilla.css';
```
For JavaScript/TypeScript projects using module bundlers (like Webpack, Rollup, or Vite), this line directly imports the pre-compiled CSS file. Ensure your bundler is configured to handle CSS imports.

Quickstart

Sets up a basic Sass build pipeline for Vanilla Framework, demonstrating how to install, import, include, and customize framework styles via Sass variables, compiling to a `dist/style.css` file.

yarn add sass vanilla-framework

// In your package.json, add a script like:
// "build-css": "sass -w --load-path=node_modules src:dist --style=compressed"

// Create a file: src/style.scss
// (The build script will compile this to dist/style.css)

// src/style.scss
// Import the entire Vanilla Framework
@import 'vanilla-framework';

// Include the main mixin to output all framework styles
@include vanilla;

// Optionally, override a Sass variable to customize the theme
$color-brand: #0073e6; // Example: Set a custom brand color

// You can also include specific parts if the entire framework is not needed:
// @include vf-b-forms; // Only include form styles

// To compile and watch for changes, run:
// yarn build-css

view raw JSON →