css-doodle: Generative CSS Art & Pattern Generator

css-doodle is a JavaScript Web Component for creating generative CSS art, geometric patterns, and animated backgrounds.

It uses CSS-like rules to style a grid of cells, with random values, math functions, SVG, and custom shapes to control the artwork.

The <css-doodle> element works in a plain HTML page. Patterns can be reproduced with a seed, updated through JavaScript, or exported as images.

Features

• Grid-based CSS patterns with configurable dimensions and cell spacing.
• Random colors, shapes, sizes, and positions with repeatable seeds.
• CSS animations and time-based effects.
• SVG artwork, filters, gradients, and polygon shapes.
• Procedural tiling, including Voronoi, lattice, and sliced patterns.
• Pointer-aware effects and WebGL shader rendering.
• JavaScript controls for updates, animation playback, and image export.
• Reusable doodle rules through CSS custom properties.

How To Use It

Installation

Load the css-doodle library from a CDN:

<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/css-doodle.min.js"></script>

npm Installation

Or install the package with NPM and import it in your JavaScript entry file.

npm install css-doodle

import 'css-doodle';

Basic Usage

Place CSS-like rules inside <css-doodle>. The @grid directive sets the number of cells, the artwork dimensions, and the background of the component. Other declarations apply to the cells.

<css-doodle>
  @grid: 8 / 320px / #152238;
  background: @p(#f9c74f, #f9844a, #90be6d, #577590);
  border-radius: @p(15%, 50%);
  scale: @r(.35, .9);
  rotate: @r(-30deg, 30deg);
  margin: 3px;
</css-doodle>

Reproduce a Pattern with a Seed

A fixed seed keeps random choices consistent across renders. Use the seed attribute when a background or illustration must keep the same appearance between page loads.

<css-doodle seed="brand-pattern-42">
  @grid: 12 / 360px / #101820;
  background: @p(#f2aa4c, #f5f0e6);
  border-radius: @p(0, 50%);
  scale: @r(.4, 1);
</css-doodle>

Refresh a Pattern with JavaScript

Call update() on the custom element to regenerate its styles. Remove a fixed seed when each update should produce a different arrangement. For built-in interaction, click:update updates the element when clicked, and auto:update="1.5s" changes it periodically.

<button id="shuffle-pattern" type="button">Shuffle pattern</button>
<script>
  document.querySelector('#shuffle-pattern').addEventListener('click', () => {
    document.querySelector('css-doodle').update();
  });
</script>

Export Artwork as an Image

The export() method resolves to an object containing SVG markup and image dimensions. Set download: true to save a PNG, or detail: true to request the generated PNG blob and its source.

const doodle = document.querySelector('css-doodle');
const image = await doodle.export({
  scale: 2,
  download: true,
  name: 'geometric-pattern'
});
console.log(image.width, image.height);

Create SVG Artwork

@svg() accepts XML or a CSS-like SVG language. Place its result in background to use it as an image, or in @content for inline SVG markup.

<css-doodle>
  @grid: 1 / 320px;
  background: @svg(
    viewBox: 0 0 100 100;
    circle {
      cx, cy: 50;
      r: 38;
      fill: #f9844a;
    }
    circle {
      cx, cy: 50;
      r: 22;
      fill: #152238;
    }
  );
</css-doodle>

Use css-doodle in React

Import css-doodle once, then place the rules inside a JSX template literal. JSX otherwise interprets braces in the doodle syntax as JavaScript expressions.

import 'css-doodle';
export function ArtPattern() {
  return (
    <css-doodle>{`
      @grid: 7 / 300px / #222;
      border-radius: @pn(100% 0, 0 100%);
      background: #fff;
    `}</css-doodle>
  );
}

Configuration and Reference

HTML Attributes for element

Doodle Properties

Properties beginning with @ are interpreted by css-doodle. Ordinary CSS properties continue to work on the individual cells.

`@grid` Modifiers

The @grid directive accepts a dimensions expression followed by optional modifiers.

Cell Selectors

Use these selectors as blocks in the doodle language. They select a specific position, conditional group, or generated element.

Functions: Cell Coordinates and Geometry

Cell functions use one-based indices for rows, columns, and the overall cell number.

Functions: Sequences

Sequence functions generate repeated values. Step functions work inside sequence expressions.

Functions: Random Values and Picks

Random outputs follow the active seed. Some pick functions process a list in sequence and others shuffle it.

Functions: Expressions and Values

Use these functions inside CSS declarations or other doodle functions.

Functions: SVG and Filters

The SVG family generates SVG markup, paths, and images from doodle expressions.

Functions: Shapes and Tiling

@shape() and @tile() are useful when artwork needs custom outlines, clipped geometry, or repeated pieces.

Tiling and Shape Controls

The following public controls belong to shape and tiling expressions. Their availability depends on the selected generator or tile mode.

Custom Shape Commands

@shape() and @plot() accept shape expressions. Coordinates can use the angle t, the point index i, or custom variables defined inside the expression.

Functions: Nested Artwork and Shaders

`@pattern()` Commands

@pattern() generates a GPU-backed pattern from its own compact syntax. Its match expressions select fills for virtual cells.

Functions: Time and Pointer Uniforms

JavaScript Element API

All element methods operate on an existing <css-doodle> node. The export() method is asynchronous. grid, seed, use, and diagnostics are JavaScript properties, not constructor options.

`export()` Options

These are the options accepted by doodle.export({ ... }). The returned object always contains width, height, and svg; PNG-related fields (blob, source) are included when a PNG is generated.

Package Exports

The npm package exposes modules for the element, generators, parsers, and metadata. The parser exports return internal syntax trees, whose structure is not a stable integration contract.

Parser Exports

css-doodle/parser also exports individual syntax parsers for editor integrations. Their returned AST is an internal representation and can change in another release.

Custom Events

Listen for these events on the <css-doodle> element. click:cell supplies the x, y, and z coordinates, the clicked cell element, and the original browser event through event.detail. A warn event can be canceled to suppress its console message.

const doodle = document.querySelector('css-doodle');
doodle.addEventListener('click:cell', (event) => {
  const { x, y, z } = event.detail;
  console.log('Clicked cell:', x, y, z);
});
doodle.addEventListener('warn', (event) => {
  console.warn(event.detail.message);
});

Styling and Customization

Regular CSS controls the component’s position and layout on the page. The public Shadow DOM parts grid and cell are also available through ::part() for external styling. To change generated cell patterns individually, write rules inside the doodle itself.

css-doodle {
  display: block;
  max-width: 100%;
}
css-doodle::part(cell) {
  transition: transform .3s ease;
}

Alternatives & Related Resources

• Create Fluid Gradient Animations With JavaScript – NeatGradients.js
• Create Dynamic Abstract Web Backgrounds With color4bg.js
• Modern Geometric Shapes Generator With JavaScript and SVG
• Random SVG Background Generator In JavaScript – rbgen.js