# Granim.js — card for AI agents

Tiny library for fluid animated gradient backgrounds on canvas, with gradient states, image blending and transitions.

Category: Video references and motion backgrounds (also: Backgrounds, patterns and shapes) · maker Benjamin Blonde (sarcadass) · checked 2026-11-05 · style: gradient, minimal

## Price
- Price: Free
- Free tier: Fully free.

## License
MIT — https://raw.githubusercontent.com/sarcadass/granim.js/master/LICENSE

- commercial: **yes** (Commercial use OK)
  > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  (https://raw.githubusercontent.com/sarcadass/granim.js/master/LICENSE)
- attribution: **no** (No credit needed)
  > The above copyright notice and this permission notice shall be included in all
  (https://raw.githubusercontent.com/sarcadass/granim.js/master/LICENSE)
- in app: **yes** (Can ship inside your app)
  > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  (https://raw.githubusercontent.com/sarcadass/granim.js/master/LICENSE)
- redistribute: **yes** (Can pass the files on to your own users)
  > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  (https://raw.githubusercontent.com/sarcadass/granim.js/master/LICENSE)

## Rules to follow
- Keep the MIT notice if you redistribute the code.

## Can an AI agent use it by itself?
**Yes** · package: Agent installs a package or loads it from a CDN

## How an agent gets files
- npm install granim (or CDN), add a <canvas>, new Granim({element, states}). (sign-in: none)
- Formats: js, html

## How to connect
- Package (npm/PyPI)
- npm: `npm install granim`
- Repository: https://github.com/sarcadass/granim.js
- Website: https://sarcadass.github.io/granim.js/

## Notes
npm granim 2.0.0.

## Numbers (AgentGid data)
- Gid Score: 22
- GitHub stars: 5,295
- Downloads last week: 3,733

## Lines to paste into your prompt or AGENTS.md

```
- Granim.js (Video references and motion backgrounds, Backgrounds, patterns and shapes). Tiny library for fluid animated gradient backgrounds on canvas, with gradient states, image blending and transitions. Price: free; commercial use OK; no credit needed. Style: gradient, minimal.
  Connect: npm granim.
  Get files: npm install granim (or CDN), add a <canvas>, new Granim({element, states}) (js, html).
  Rule: Keep the MIT notice if you redistribute the code.
  License: https://raw.githubusercontent.com/sarcadass/granim.js/master/LICENSE (checked 2026-11-05; details: https://agentgid.com/assets/granim-js/)
```

## Links
- AgentGid page: https://agentgid.com/assets/granim-js/
- Is it free for commercial use? https://agentgid.com/assets/granim-js/commercial-use/
- Source: https://sarcadass.github.io/granim.js/
- Source: https://raw.githubusercontent.com/sarcadass/granim.js/master/LICENSE
- Source: https://registry.npmjs.org/granim/latest


## Granim.js: slowly shifting color gradients behind your content

Granim.js is a small free code library that fills a box on a web page with a color gradient that slowly changes from one set of colors to the next. You pick the colors and the direction, and it draws them behind your headline or card. It can also blend the colors with a picture and switch to other colors when a visitor clicks something.

### Where to use it
- A moving background for a hero: Put a slowly shifting gradient behind the big headline at the top of a landing page, so the first screen feels alive without a video.
- Colors that answer a click: Switch the background to another set of colors when a visitor picks a plan, a mood or a dark theme, with a smooth fade between them.
- Colored light over a photo: Lay the moving colors over your own photo with a blend mode such as multiply or screen, for a tinted header picture.
- A logo or title filled with moving color: Show the moving gradient only inside a shape, such as your logo or a large word, by placing a cut-out picture over the canvas.
- Text that stays readable on any color: Let the library mark the page as dark or light while the colors change, so your styles can switch the text between white and black.
- A calm backdrop for a waiting screen: Fill a loading, sign-in or "coming soon" screen with slow color changes, so the empty page looks finished while people wait. (idea, not from the official pages)

### How to start
- Install the package, or download the ready file from the project's releases page.

```
npm install granim --save
```

- Add a canvas where the gradient should appear, load the script and create a Granim instance with at least one state of gradients.

```
<!-- Create a <canvas> element -->
<canvas id="granim-canvas"></canvas>

<!-- Call the script -->
<script src="granim.min.js"></script>

<!-- Create a Granim instance -->
<script>
var granimInstance = new Granim({
   element: '#granim-canvas',
   name: 'granim',
   opacity: [1, 1],
   states : {
       "default-state": {
           gradients: [
               ['#834D9B', '#D04ED6'],
               ['#1CD8D2', '#93EDC7']
           ]
       }
   }
});
</script>
```

- Give the canvas a size with CSS (for a background, stretch it over its parent box) and put your content above it.

### License
MIT license: free to use in personal and paid sites, and you may change and share the code. No visible credit is needed; keep the license notice when you pass the code on.

### Good to know
- The last release, 2.0.0, came out in 2018. The library is small and has no other packages, but expect no new features or fixes.
- Every gradient in one setup must have the same number of colors. Mixing two-color and three-color gradients does not work.
- The animation pauses on its own when the visitor switches browser tabs. It keeps running while scrolled out of view unless you turn on the pause option.
- Blending with a picture works only when you give it both a picture and gradients, and the picture must be your own or one you may use.

Checked 2026-11-12 against: https://sarcadass.github.io/granim.js/, https://sarcadass.github.io/granim.js/examples.html, https://sarcadass.github.io/granim.js/api-v2.0.0.html, https://github.com/sarcadass/granim.js, https://github.com/sarcadass/granim.js/blob/master/README.md, https://github.com/sarcadass/granim.js/blob/master/LICENSE, https://registry.npmjs.org/granim

### Mistakes to avoid
- Don't: gradients: [['#ff9966', '#ff5e62'], ['#00f260', '#0575e6', '#e1eec3']] → Do: Give every gradient in every state the same number of colors (Gradients with different numbers of colors are not supported.)
- Don't: A bare <canvas> with no CSS size, expecting it to cover the section → Do: Stretch the canvas over its box with position absolute, width 100% and height 100%, and put the content above it (The docs' examples size the canvas with CSS; our demo canvases only filled their boxes with these rules.)
- Don't: Leaving several animated canvases running while they are scrolled out of view → Do: Set isPausedWhenNotInView: true, and call destroy() when the block is removed from the page (By default the animation keeps running off screen; it only pauses on a tab change.)
- Don't: image: { blendingMode: 'multiply' } with no source, or an image with no gradients → Do: Pass both image.source and the gradients (The blend only works with an image and gradients set.)

### Questions
- Which color formats can I use? Hex, rgb, rgba, hsl and hsla. You can also set where each color sits in the gradient with a position from 0 to 1.
- Which directions are there? Diagonal (the default), left to right, top to bottom, radial, and a custom direction set in pixels or percentages.
- Can I stop or change the animation from my own code? Yes. The instance has play, pause, clear, changeState, changeDirection, changeBlendingMode and destroy methods.
- How fast do the colors change? By default each change between two gradients takes 5 seconds, and a switch to another state takes 1 second; both are settings in milliseconds.
- Can I use it in a paid product? Yes. The MIT license allows use, change and sale of copies; keep the license notice with the code.

---
AgentGid's catalog is curated: every entry was checked against the maker's official pages (registry, repository, license and pricing pages) on the date shown; a license value shows the quote it stands on wherever AgentGid has one. Usage numbers come from AgentGid's own scan of public repositories set up for AI coding agents. Claims by makers are reported, not tested by AgentGid.
