# css-doodle

> css-doodle is a web component for visual art and creative coding with CSS. Rules written inside a `<css-doodle>` element are applied to every cell of a grid, and functions such as `@i`, `@r` and `@p` give each cell its own value.

Load it from a CDN, or install it with `npm install css-doodle` and `import 'css-doodle'`:

```html
<script type="module" src="https://esm.sh/css-doodle"></script>

<css-doodle>
  @grid: 7 / 60vmin / #333;
  border-radius: @pn(100% 0, 0 100%);
  background: #fff;
</css-doodle>
```

Notes:

- `@grid` takes the cell count (`5` or `10x8`, columns x rows), then optionally a size and a background after `/`, e.g. `@grid: 5x5 / 60vmin / #96c`.
- Functions are evaluated once per cell; all other declarations are regular CSS.
- A doodle clips its cells by default, so `overflow: hidden` is not needed; `@grid: 5 noclip` lets them overflow.

## Guides

- [Getting started](https://css-doodle.com/getting-started): Install css-doodle and write your first doodle.
- [Start from a grid](https://css-doodle.com/start-from-grid): A short walk from one grid to a finished piece.
- [Syntax overview](https://css-doodle.com/syntax-overview): The language map: statements, functions, selectors and expressions.
- [CLI tool](https://css-doodle.com/cli): Preview, render and export doodles from the terminal.
- [MCP server](https://css-doodle.com/mcp-server): Let an AI assistant read these docs and check its code.
- [Resources](https://css-doodle.com/resources): Articles, tutorials and talks, plus the tools around css-doodle.

## Attributes

HTML attributes on the <css-doodle> element.

- [grid](https://css-doodle.com/reference/attribute-grid): Number of columns and rows, and an optional depth.
- [seed](https://css-doodle.com/reference/attribute-seed): Starting value for random functions such as @r and @p. Same seed, same image.
- [use](https://css-doodle.com/reference/attribute-use): Load rules from CSS custom properties, or pass the code as the attribute value.
- [click:update](https://css-doodle.com/reference/attribute-click-update): Re-render the doodle when it is clicked, with a new random seed.
- [auto:update](https://css-doodle.com/reference/attribute-auto-update): Re-render the doodle on an interval.
- [experimental](https://css-doodle.com/reference/attribute-experimental): Raise the grid limit from 64 to 256 per axis.
- [ignore-reduced-motion](https://css-doodle.com/reference/attribute-ignore-reduced-motion): Keep animating when the user prefers reduced motion.

## Selectors

Target the component, the grid container, or a subset of cells.

- [:doodle](https://css-doodle.com/reference/selector-doodle): The component element itself.
- [:container](https://css-doodle.com/reference/selector-container): The grid element that holds the cells.
- [@nth](https://css-doodle.com/reference/selector-nth): Cells by index, like :nth-child.
- [@at](https://css-doodle.com/reference/selector-at): The cell at a column and row.
- [@row](https://css-doodle.com/reference/selector-row): Cells in the given rows. @y is an alias.
- [@col](https://css-doodle.com/reference/selector-col): Cells in the given columns. @x is an alias.
- [@depth](https://css-doodle.com/reference/selector-depth): Cells at the given depths. @z is an alias.
- [@even](https://css-doodle.com/reference/selector-even): Checkerboard: cells where column + row is odd.
- [@odd](https://css-doodle.com/reference/selector-odd): Checkerboard: cells where column + row is even.
- [@random](https://css-doodle.com/reference/selector-random): Cells picked by probability or count.
- [@match](https://css-doodle.com/reference/selector-match): Cells where an expression is true.
- [@cell](https://css-doodle.com/reference/selector-cell): One selector for index, expression and random rules.
- [Nesting & pseudo](https://css-doodle.com/reference/selector-nesting): :hover, ::after, descendants and the & selector.
- [At-rules](https://css-doodle.com/reference/selector-at-rules): @keyframes, @media, @font-face and friends.

## Properties

Directives that css-doodle handles instead of emitting as CSS.

- [@grid](https://css-doodle.com/reference/property-grid): Grid dimensions plus size, fill, gap, scale, rotation and more.
- [@size](https://css-doodle.com/reference/property-size): Width and height in one declaration, with paper size presets.
- [@place](https://css-doodle.com/reference/property-place): Take a cell out of the grid and position its center at a point.
- [@gap](https://css-doodle.com/reference/property-gap): Gap between cells, optionally with a rule drawn inside it.
- [@content](https://css-doodle.com/reference/property-content): Put text, SVG, a nested doodle or a shader canvas inside a cell.
- [@shape](https://css-doodle.com/reference/property-shape): Clip the cell to a preset shape.
- [@seed](https://css-doodle.com/reference/property-seed): Set the random seed from inside the code.
- [@use](https://css-doodle.com/reference/property-use): Insert rules stored in CSS custom properties.

## Functions

Values computed per cell: position, sequences, randomness, SVG and more.

- [@i, @I](https://css-doodle.com/reference/function-i): Cell index from 1, and the cell count.
- [@x, @X](https://css-doodle.com/reference/function-x): Column from 1, and the number of columns.
- [@y, @Y](https://css-doodle.com/reference/function-y): Row from 1, and the number of rows.
- [@z, @Z](https://css-doodle.com/reference/function-z): Depth from 1, and the depth count. A third grid number nests cells inside cells.
- [@iI, @Ii](https://css-doodle.com/reference/function-ii): Index as a 0–1 ratio for linear interpolation, forward and backward.
- [@xX, @Xx](https://css-doodle.com/reference/function-xx): Column as a 0–1 ratio, forward and backward.
- [@yY, @Yy](https://css-doodle.com/reference/function-yy): Row as a 0–1 ratio, forward and backward.
- [@dx, @dy, @dr …](https://css-doodle.com/reference/function-dx): Offsets, distances and angle from the grid center.
- [@id](https://css-doodle.com/reference/function-id): The id of the cell element; a class of the same name on a depth tree.
- [@m, @M, @rep](https://css-doodle.com/reference/function-m): Repeat a value N times, joined by comma, space or nothing.
- [@n, @N, @nx, @ny](https://css-doodle.com/reference/function-n): The current step and the step count inside @m.
- [@nN, @Nn](https://css-doodle.com/reference/function-nn): Step as a 0–1 ratio, forward and backward, with easing.
- [@nd](https://css-doodle.com/reference/function-nd): Step as an offset from the middle of the sequence.
- [@r, @ri](https://css-doodle.com/reference/function-r): Random number in a range; @ri keeps the integer part.
- [@R](https://css-doodle.com/reference/function-r-upper): Random value from 2D noise, so neighbouring cells get similar values.
- [@p, @P](https://css-doodle.com/reference/function-p): Pick one value at random; @P never repeats the last pick at that call.
- [@pn, @pnr](https://css-doodle.com/reference/function-pn): Pick values in order, or backwards.
- [@pd](https://css-doodle.com/reference/function-pd): Pick values in a shuffled order, each once per round.
- [@PN, @PNR, @PD](https://css-doodle.com/reference/function-pn-upper): Like @pn, @pnr and @pd, but they follow the enclosing sequence step.
- [@lp, @lr](https://css-doodle.com/reference/function-lp): Reuse the last picked or last random value.
- [@cycle](https://css-doodle.com/reference/function-cycle): All rotations of a list, for use with a pick function.
- [@mirror, @Mirror](https://css-doodle.com/reference/function-mirror): A list followed by its reverse.
- [@reverse](https://css-doodle.com/reference/function-reverse): A list, or an SVG path, backwards.
- [@stripe](https://css-doodle.com/reference/function-stripe): Hard-edged gradient stops from a list of colors.
- [@palette](https://css-doodle.com/reference/function-palette): A list of colors that go together, picked by the seed.
- [@once](https://css-doodle.com/reference/function-once): Evaluate once and share the value across cells.
- [@match](https://css-doodle.com/reference/function-match): Choose a value by condition.
- [$ (calc)](https://css-doodle.com/reference/function-dollar): Evaluate an arithmetic expression with variables.
- [@var](https://css-doodle.com/reference/function-var): A var() that css-doodle leaves alone.
- [@raw](https://css-doodle.com/reference/function-raw): Text that css-doodle passes through untouched.
- [@code](https://css-doodle.com/reference/function-code): Characters from UTF-16 code units.
- [@hex](https://css-doodle.com/reference/function-hex): A number in hexadecimal.
- [@<Math>](https://css-doodle.com/reference/function-math): Every JavaScript Math function and constant, plus π.
- [@google-font](https://css-doodle.com/reference/function-google-font): Load a Google font by name.
- [@svg](https://css-doodle.com/reference/function-svg): Creates an SVG image from XML or a CSS-like syntax.
- [@svg-filter](https://css-doodle.com/reference/function-svg-filter): An SVG filter for filter and backdrop-filter.
- [@svg-polygon](https://css-doodle.com/reference/function-svg-polygon): An SVG image of a polygon drawn from shape commands.
- [@svg-pattern](https://css-doodle.com/reference/function-svg-pattern): One SVG pattern tile, repeated to fill the element.
- [@linearGradient, @radialGradient](https://css-doodle.com/reference/function-svg-gradient): SVG linear and radial gradients for fill or stroke inside @svg.
- [@arc](https://css-doodle.com/reference/function-arc): The path data of an arc, for a path d. Arcs chain into one path.
- [@invert](https://css-doodle.com/reference/function-invert): Swap the axes of an SVG path.
- [@flip, @flipH, @flipV](https://css-doodle.com/reference/function-flip): Mirror an SVG path.
- [@shape](https://css-doodle.com/reference/function-shape): A polygon() from a preset name or polar equations.
- [@plot, @Plot](https://css-doodle.com/reference/function-plot): One point of a shape per cell: percentages, or raw coordinates with @Plot. .scatter fills the shape.
- [@tile](https://css-doodle.com/reference/function-tile): A shape cut into pieces, one per cell, for clip-path.
- [@doodle](https://css-doodle.com/reference/function-doodle): A nested doodle as an image, or as an element with @content.
- [@shaders](https://css-doodle.com/reference/function-shaders): A GLSL fragment shader, run on the GPU with WebGL.
- [@pattern](https://css-doodle.com/reference/function-pattern): A small language for drawing on a grid of cells, compiled to a GPU shader.
- [@t, @ts, @T, @TS](https://css-doodle.com/reference/function-t): Milliseconds since the doodle rendered, or since midnight; seconds with @ts and @TS.
- [@ux, @uy](https://css-doodle.com/reference/function-ux): Pointer position over the doodle.
- [@uw, @uh](https://css-doodle.com/reference/function-uw): Width and height of the doodle in pixels.
- [@udx, @udy](https://css-doodle.com/reference/function-udx): Offset from the pointer to the cell center, in pixels.

## JS APIs

Methods and properties on the element, and the modules the package exports.

- [update()](https://css-doodle.com/reference/js-api-update): Re-render, optionally with new code.
- [export()](https://css-doodle.com/reference/js-api-export): Export the doodle as SVG or PNG.
- [pause(), resume()](https://css-doodle.com/reference/js-api-pause): Pause and resume the animations.
- [autoUpdate()](https://css-doodle.com/reference/js-api-auto-update): Start or stop periodic re-rendering.
- [grid](https://css-doodle.com/reference/js-api-grid): Read the grid dimensions, or set the grid attribute.
- [seed](https://css-doodle.com/reference/js-api-seed): Read the seed in use, or set the seed attribute.
- [use](https://css-doodle.com/reference/js-api-use): Read or set the use attribute.
- [diagnostics](https://css-doodle.com/reference/js-api-diagnostics): Warnings from the last render.
- [Package exports](https://css-doodle.com/reference/js-api-modules): The ES module entries: css-doodle/component, /generator, /parser and /meta.
- [svg()](https://css-doodle.com/reference/js-api-svg): SVG markup from @svg code, as a string or an element.
- [shape()](https://css-doodle.com/reference/js-api-shape): A polygon() from @shape code, as a string.
- [prerender()](https://css-doodle.com/reference/js-api-prerender): Render a doodle to HTML ahead of time, so it paints without the runtime.

## Events

Custom events dispatched on the element.

- [render](https://css-doodle.com/reference/event-render): The doodle has rendered, first time or after an update.
- [beforeUpdate](https://css-doodle.com/reference/event-beforeupdate): An update is about to start.
- [update](https://css-doodle.com/reference/event-update): An update has finished.
- [click:cell](https://css-doodle.com/reference/event-click-cell): A cell was clicked, with its column and row.
- [warn](https://css-doodle.com/reference/event-warn): A problem was found in the code. Cancel it to keep it out of the console.

## Optional

- [Reference index](https://css-doodle.com/reference): Every attribute, selector, property, function, JS API and event on one page.
- [Playground](https://css-doodle.com/new): Write and preview a doodle in the browser.
- [SVG generator](https://css-doodle.com/svg): Build SVG images with the `@svg` syntax.
- [Shape generator](https://css-doodle.com/shapes): Build `polygon()` shapes with the `@shape` syntax.
- [Discover](https://css-doodle.com/discover): Doodles shared by the community.
- [Source code](https://github.com/css-doodle/css-doodle): The css-doodle repository on GitHub.