Getting Started

Meteocons ships as three npm packages — animated SVG, static SVG, and Lottie JSON. Pick the format that fits your project, or install multiple.

Which format should I use?

Recommendation: use SVG for web projects, SVG Static when animations are not supported (e.g. emails), and Lottie when you need playback control or are building a native app.

Installation

SVG icons

bun add @meteocons/svg

npm install @meteocons/svg

yarn add @meteocons/svg

pnpm add @meteocons/svg

Static SVG icons

bun add @meteocons/svg-static

npm install @meteocons/svg-static

yarn add @meteocons/svg-static

pnpm add @meteocons/svg-static

Lottie icons

bun add @meteocons/lottie

npm install @meteocons/lottie

yarn add @meteocons/lottie

pnpm add @meteocons/lottie

All packages

bun add @meteocons/svg @meteocons/svg-static @meteocons/lottie

npm install @meteocons/svg @meteocons/svg-static @meteocons/lottie

yarn add @meteocons/svg @meteocons/svg-static @meteocons/lottie

pnpm add @meteocons/svg @meteocons/svg-static @meteocons/lottie

Quick start

SVG — image tag

The simplest way to render an icon. Animations start automatically.

<img
    src="https://cdn.meteocons.com/latest/svg/fill/clear-day.svg"
    alt="Clear day"
    width="64"
    height="64"
/>

SVG — bundler import

With a bundler like Vite, Webpack, or Turbopack you can import SVGs directly:

import clearDay from '@meteocons/svg/fill/clear-day.svg';

const img = document.createElement('img');
img.src = clearDay;
img.width = 64;
img.height = 64;
img.alt = 'Clear day';
document.body.appendChild(img);

SVG — inline for full control

Fetch and inline the SVG to access individual elements, apply CSS, or control animations:

const response = await fetch('https://cdn.meteocons.com/latest/svg/fill/clear-day.svg');
const svgMarkup = await response.text();

const container = document.getElementById('weather-icon');
container.innerHTML = svgMarkup;

// Now you can style individual elements with CSS
const svg = container.querySelector('svg');
svg.style.width = '128px';
svg.style.height = '128px';

Lottie — web

Install lottie-web alongside the icon package:

bun add @meteocons/lottie lottie-web

npm install @meteocons/lottie lottie-web

yarn add @meteocons/lottie lottie-web

pnpm add @meteocons/lottie lottie-web

import lottie from 'lottie-web';
import clearDayAnimation from '@meteocons/lottie/fill/clear-day.json';

const animation = lottie.loadAnimation({
    container: document.getElementById('weather-icon'),
    animationData: clearDayAnimation,
    renderer: 'svg',    // or 'canvas' for better performance
    loop: true,
    autoplay: true
});

// Control playback
animation.setSpeed(0.5);    // half speed
animation.pause();
animation.play();
animation.destroy();        // clean up when done

CDN usage

Use icons directly from a CDN without installing anything. Great for prototyping or static HTML pages.

<!-- Meteocons CDN -->
<img
    src="https://cdn.meteocons.com/latest/svg/fill/clear-day.svg"
    alt="Clear day"
    width="64"
    height="64"
/>

<!-- unpkg -->
<img
    src="https://unpkg.com/@meteocons/svg/fill/clear-day.svg"
    alt="Clear day"
    width="64"
    height="64"
/>

<!-- jsDelivr -->
<img
    src="https://cdn.jsdelivr.net/npm/@meteocons/svg/fill/clear-day.svg"
    alt="Clear day"
    width="64"
    height="64"
/>

See the CDN documentation for the full URL structure, Lottie examples, and versioning tips.

Package structure

All packages follow the same layout with four icon styles:

@meteocons/svg/
├── fill/              Filled, colorful icons with gradients
├── flat/              Flat design — solid colors, no gradients
├── line/              Outline-based, minimal weight
├── monochrome/        Single-color, inherits currentColor
├── manifest.json      Icon metadata and categories
└── index.d.ts         TypeScript type definitions

Every style directory contains one file per icon, named by slug:

fill/clear-day.svg
fill/rain.svg
fill/snow.svg
fill/thunderstorms-day-rain.svg

The @meteocons/svg-static and @meteocons/lottie packages have the same structure. @meteocons/svg-static contains .svg files without SMIL animations, and @meteocons/lottie contains .json files.

Styles

Meteocons comes in four distinct styles. Every icon is available in all four.

The monochrome style is special — it uses currentColor, so the icons automatically match your text color. This makes it ideal for dark mode or themed interfaces. Use inline SVG or CSS mask-image for color inheritance — <img> tags render SVGs in an isolated context where currentColor doesn’t apply. See Usage — Dark mode with monochrome for detailed examples.

/* Icons follow the text color */
.weather-widget {
    color: #334155;
}

/* Dark mode — icons adapt automatically */
@media (prefers-color-scheme: dark) {
    .weather-widget {
        color: #e2e8f0;
    }
}

TypeScript

Both packages ship with TypeScript declarations. Import types directly:

import type { IconManifest, IconCategory, IconEntry } from '@meteocons/svg';
import manifest from '@meteocons/svg/manifest.json';

// Full type safety
const categories: IconCategory[] = manifest.categories;
const firstIcon: IconEntry = categories[0].icons[0];

console.log(firstIcon.slug);     // "clear-day"
console.log(firstIcon.animated);  // true

Next steps

• Usage patterns — inline SVG, lazy loading, dynamic icons, accessibility
• Framework guides — React, Vue, Svelte, Angular, and more
• API reference — types, manifest, naming conventions