Open-source project
pablof7z/chardin.js avatar
pablof7z/chardin.js

chardin.js keeps overlay instructions in data attributes on the page

Simple overlay instructions for your apps.

4,952 stars484 forksJavaScriptNOASSERTION

At a glance

What is it?
chardin.js is a jQuery plugin that puts a guided overlay on elements you already have, with the text living in data-intro and the placement in data-position. It has one release, tagged in 2020, while commits to the default branch continued into 2026, and its metadata names two other repositories.
Who is it for?
chardin.js fits a page that already has jQuery, needs a short product tour or a first-run explainer, and is happy to hand-edit attributes and a stylesheet rather than depend on a package. It does not fit a build that has moved off jQuery, a tour whose order must be stable across DOM changes, or a team that needs a maintained release trail.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 40 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pablof7z/chardin.js4,952 ★ · +0
Star history
Repository2026-09-232026-11-15
pablof7z/chardin.js5k5k

0 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The instruction text and its placement both live in attributes

There is no separate configuration file to write. The text of a step is a `data-intro` attribute on the element the overlay points at, and the placement is `data-position`, which takes `left`, `top`, `right` or `bottom`.

Positioning has two refinements that are easy to miss. A colon and a percentage from -100 to 100 after the position slides the tooltip along the length or height of the element, away from its centre, so `top:-50` pushes it up along that axis. A comma and a percentage after that offset increases the distance between the tooltip and the element, with the documented values being 100, 200, 300, 400 or 500, so `top:0,200` sits twice as far away as the default.

Both are arithmetic expressed inside a string, and nothing states what happens to a value outside those ranges or to a position word that does not exist. If a tooltip lands somewhere unexpected, the attribute is the first thing to read.

Sequenced mode follows the DOM, and shift-click walks backwards

Sequenced mode shows one element at a time and moves on with a mouse click, or automatically after a delay. It is switched on with attributes on the body tag:

HTML
<body data-chardin-sequenced="true" data-chardin-auto="false" data-chardin-delay="800" >

`data-chardin-auto="true"` adds automatic movement through the elements, and `data-chardin-delay` is the pause in milliseconds between steps. Clicking advances through the elements, and clicking with the shift key held down moves backwards through them.

The ordering is the part with consequences. The default sequence is the order the elements were loaded by the DOM, and it can be overridden with a `data-sequence` attribute carrying a number. So a tour whose steps are numbered in the markup has to keep that numbering correct after a template change: move one element earlier in the document and the guided order moves with it. That is convenient for a static page and a trap for a page assembled from dynamic content, where the load order is whatever the app happened to render.

The started instance is parked in jQuery data, which is how you toggle it

Initialising and starting are separate steps, and the object the library creates is stored on the containing element's data set. That is what makes the toggle work:

Javascript
$('body').chardinJs();
$('body').on('click', 'button[data-toggle="chardinjs"]', function (e) {
    e.preventDefault();
    return ($('body').data('chardinJs')).toggle();
});

The same selector also works as an explicit call, `$('body').chardinJs('start')`, and the three methods are start, toggle and stop. Confining the overlay to part of a page instead of the whole document is done by changing the selector, so `$('.container').chardinJs('start')` limits it to that container.

There is a refresh method for the case where the page changed underneath a visible overlay: the return value of the start call is the overlay, and `chardinOverlay.refresh()` re-reads the underlying elements. That matters for pages that populate content after load, since the alternative is closing and reopening the tour.

External JSON text never overrides an attribute

The overlay text can also live outside the page. The constructor takes a `url` option pointing at something that returns a JSON object:

Javascript
$('body').chardinJs({ url: "/help/HelpOverlay.json" });

The file is a set of name-value pairs. A name beginning with `#` matches a `data-intro` attribute, so `"#search-btn"` addresses the element carrying `data-intro='#search-btn'`; a `data-intro` value that does not start with `#` is used as the text itself. Each value carries the text and an optional position.

The precedence rule is the useful part: for conflicts between the data attributes and the JSON entries, the attribute takes precedence. And if no entry is present for a given element's data reference, nothing is displayed. That last rule means a typo in a key is invisible, since a missing entry and an element with no instruction look identical on the page. The `attribute` option is the escape hatch for projects that cannot use `data-intro`, changing the attribute the library reads to `data-` plus whatever you specify.

One release in 2020, commits on master through 2026

The version story is short. `package.json` says 0.2.0, and the repository has exactly one tagged release, v0.2.0, published on 2020-02-15. The last push to the default branch was on 2026-10-06 and the repository is not archived, so work has continued on master for six years without a new tag.

For a plugin installed by copying files, as the README describes, that gap matters less than it would for a package. The version number is also the honest summary of the API surface: start, toggle, stop, refresh, two options, and four events, `chardinJs:start`, `chardinJs:stop`, `chardinJs:next` and `chardinJs:previous`.

The build is node-sass and terser, both pinned exactly

The build scripts are three commands wrapped in one. `build:css` and `build:min.css` run node-sass over `chardinjs.scss` to produce `chardinjs.css` and `chardinjs.min.css` with source maps, and `build:js` runs terser to produce `chardinjs.min.js` with a source map that includes sources. `build` chains all three. Both tools are pinned to exact versions in devDependencies, node-sass 9.0.0 and terser 4.8.1, so a fresh install gets the same compiler rather than a drifting one.

There is exactly one runtime dependency, `jquery` at `^3.5.1`, and the entry point in the manifest is `chardinjs.js`. The repository ships all four forms of the asset, `chardinjs.scss`, `chardinjs.css`, `chardinjs.js` and `chardinjs.min.js`, which is what makes the copy-two-files install in the readme work.

One oddity belongs to the Rails side rather than the JavaScript. Alongside `package.json` and `package-lock.json` the top level contains a `Gemfile` and a `Rakefile`, and the readme points at a `chardinjs-rails` gem. The README does not say what those Ruby files are for, while the JavaScript build runs on npm scripts.

The metadata names two repositories that are not this one

Following the links in this project leads somewhere unexpected. The readme's asset links point at `heelhook/chardin.js` for `chardinjs.css` and `chardinjs.min.js`, and the demo links point at a `heelhook.github.io` address. The manifest repeats that name in `bugs` and `homepage`, while its `repository` field says `git://github.com/wprl/chardin.js.git`, a third owner. The repository you are reading is under `pablof7z`.

The licence is the other place to look. The repository's licence field reads NOASSERTION, while `package.json` says `Apache 2.0` and the licence text at the bottom of the readme is the Apache License, Version 2.0, copyright 2020 Pablo Fernandez. Those two agree with each other, so the odd one out is the metadata field rather than the terms.

Neither point is a blocker for using the code, and both are reasons to read the licence text and the file list yourself rather than trusting the badge. The top level is short enough to audit by hand: a `LICENSE`, a `Rakefile`, a `Gemfile`, the four asset files, `package.json`, `package-lock.json` and an `example/` directory holding `index.html`, `sequential.html`, and `css/`, `img/` and `js/` subfolders.

Editorial conclusion

chardin.js fits a page that already has jQuery, needs a short product tour or a first-run explainer, and is happy to hand-edit attributes and a stylesheet rather than depend on a package. It does not fit a build that has moved off jQuery, a tour whose order must be stable across DOM changes, or a team that needs a maintained release trail. Before adopting, check which repository the links in the metadata actually point at, confirm the Apache 2.0 licence text you are copying, and decide whether you want the overlay text in attributes or in a JSON file fetched at runtime.

Frequently asked questions

How do I install chardin.js?

Fork the repository or download chardinjs.css and chardinjs.min.js, then add both to your page with `<link href="chardinjs.css" rel="stylesheet">` and `<script src="chardinjs.min.js"></script>`. The plugin needs jQuery, listed as the single runtime dependency at ^3.5.1. A chardinjs-rails gem also exists for Rails applications.

How do I start and stop the chardin.js overlay?

Initialise with `$('body').chardinJs();` and the library stores an initialised object in that element's data set, so a button can call `($('body').data('chardinJs')).toggle()`. You can also start explicitly with `$('body').chardinJs('start')`, and the three methods are start, toggle and stop. Replacing `body` with another selector confines the overlay to that container.

Can chardin.js load overlay text from a JSON file?

Yes, pass the url option: `$('body').chardinJs({ url: "/help/HelpOverlay.json" });`. The file holds name-value pairs, where a name beginning with # matches a data-intro attribute and a data-intro value without it is used as the text itself. Where an attribute and a JSON entry conflict the attribute wins, and an element with no matching entry displays nothing.

Official sources

  1. Issues
  2. pablof7z/chardin.js on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pablof7z-chardin-js.svg)](https://hysenlabs.com/projects/pablof7z-chardin-js)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pablof7z-chardin-js.svg)](https://hysenlabs.com/projects/pablof7z-chardin-js)

Was this useful?