Registry / web-framework / vanilla-framework

vanilla-framework

library4.49.0jsnpmunverified

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.

web-framework

npm install vanilla-framework

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VANILLA-FRAMEWORK

vanilla-framework

web-frameworkjavascriptv4.49.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

vanilla-framework

✓ @import 'vanilla-framework';

✗ @import 'node_modules/vanilla-framework/scss/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

✓ @include vanilla;

✗ @import '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

✓ import 'vanilla-framework/dist/vanilla.css';

✗ import 'vanilla-framework/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.

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

Debug

Known issues

breakingMinor 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.

affects: >=4.0.0

gotchaUsing 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`.

affects: <1.79.0

gotchaWhile 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.

affects: *

gotchaDirectly 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.

affects: *

Errors

Common errors & fixes

Error: Undefined variable: "$my-custom-color".

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";

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".

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.

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.

Upgrade

Version history

4.49.0latest on npm

Audit

Dependencies

sassrequiredRequired for compiling Vanilla Framework's Sass files, which is the primary and recommended method for integrating and customizing the framework within a project.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/canonical/vanilla-framework ↗

packagehttps://www.npmjs.com/package/vanilla-framework ↗

homepagehttps://vanillaframework.io ↗