chardin.js: Gmail's composer tour, generalized into two files and data attributes

Inspired by a Gmail tour, named for a painter

The library creates a simple overlay to display instructions on existent elements, and its inspiration is credited specifically, the recent Gmail new composer tour which the author loved, the interaction pattern where an interface dims and short annotations appear beside the controls that matter. The name honors Jean-Baptiste-Simeon Chardin, the eighteenth century French still life painter, a choice matching the project's aesthetic of quiet, small compositions. Pablo Fernandez authored it under the heelhook account originally, and the repository's history now lives in forks, with the package metadata pointing at wprl's fork and the current home at pablof7z, while the demo pages remain hosted under the original heelhook.github.io address, a genealogy worth knowing when links stop resolving.

Two files, one dependency, no build for users

Installation is deliberately primitive, fork the repository or download chardinjs.css and chardinjs.min.js and add both assets to your HTML:

<link href="chardinjs.css" rel="stylesheet">
<script src="chardinjs.min.js"></script>

and the first run is two jQuery calls, initializing the plugin and wiring a toggle button:

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

There is even a chardinjs-rails gem for Rails asset pipelines of the era. The npm package carries a single runtime dependency, jquery at 3.5.1 or later, and the build toolchain for maintainers is two tools, node-sass compiling chardinjs.scss into the css, and terser minifying the source. For an integrating developer the story ends at two file copies, no bundler, no npm step, no framework, which is why the library survived so long in legacy codebases, and why the repository root still contains the built artifacts beside their sources rather than only the source.

data-intro and data-position carry the annotation

Annotating an element takes two attributes, data-intro holding the text to show with the instructions tooltip, and data-position choosing left, top, right or bottom for where the text sits relative to the element. The positioning grammar grows more precise than the four words suggest, a colon and a percentage from minus 100 to 100 after the position, as in top:-50, slides the tooltip along the element away from center, and a comma plus a percentage from the set 100 through 500, as in top:0,200, shifts the tooltip to be twice farther away than default. That two-axis tuning, along the element and away from it, is what makes the overlay readable on crowded interfaces where every default position collides with something. The two attributes alone are enough for a working overlay, everything else in the library is refinement, which is why the annotation model survived unmodified across the project's lifetime.

Sequenced mode: one element at a time

Beyond showing everything at once, chardin.js runs in sequenced mode where one element displays at a time, moving on with a mouse click or automatically after a set delay, configured through attributes on the body tag:

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

data-chardin-sequenced set to true activates the mode, data-chardin-auto enables automatic movement, and data-chardin-delay is in milliseconds. The default sequence order follows the DOM, and a data-sequence number overrides it, so the tour's path is markup-driven rather than JavaScript-configured. Without auto traversal, plain clicks advance and shift-clicks move backward, giving the presenter control in a live demo, and the second hosted demo page shows the sequential flow working end to end.

start, toggle, stop, and the stored instance

Running the overlay follows jQuery plugin conventions. Initializing with $('body').chardinJs() stores the instance in the element's data set, and the documented binding wires a toggle button through the data attribute selector, preventing default and calling toggle on the stored object. Explicit control exists too, $('body').chardinJs('start') to begin, and stop does exactly what its documentation jokes about, make your best guess, that's right, stops it. Scoping is a selector swap, confining the overlay to a particular container by calling chardinJs on $('.container') instead of body. The refresh method updates an already displayed overlay to reflect changes in the underlying page elements, the hook dynamic interfaces need when their layout shifts while a tour is showing. The refresh method pairs naturally with the sequential mode, since a single page application can mutate its DOM between steps and the overlay follows, keeping annotation targets honest rather than pointing at elements that moved.

JSON for the text, attributes for the hooks

The constructor accepts options, and the url option points at a JSON file returning the overlay text, useful for dynamically changing the overlay or holding all the text in one external file. The JSON is a set of name value pairs where names match data-intro attributes beginning with a hash, each value carrying the required text and an optional position, with the documented example showing entries for a summary buttons element and a search button. Precedence is specified, for conflicts between the data attributes and the JSON entries, the attribute takes precedence, and an element whose reference has no entry displays nothing. A second option, attribute, renames the hook itself from data-intro to a custom attribute, the escape hatch for applications that already use data-intro for something else. The split has a practical maintenance consequence, marketing and support teams can edit the external JSON as content while the engineering team owns the markup, and neither side's edits collide with the other's.

Four events, eleven contributors, Apache 2.0

The event surface is small and sufficient, chardinJs:start and chardinJs:stop fire on the obvious transitions, and chardinJs:next and chardinJs:previous fire as the sequential mode moves between elements, enough to drive analytics or coordinate other UI reactions to a tour. Eleven contributors are credited by name, John Weir through dozyatom, with the contribution process written for a different era, fork, add your feature, add yourself to the contributors list, send a pull request. The license is Apache 2.0, stated in the README's license section and matching the LICENSE file and package metadata, though GitHub's automated detection reports NOASSERTION, so compliance teams should read the file itself. One tagged release exists, 0.2.0 from 2020-02-15, with the last push on 2026-06-16 keeping the fork lineage alive. For evaluation, the honest reading of the version history is that the library is finished rather than abandoned, its scope is small enough that one release covers it, and the continued pushes indicate the fork lineages still merge fixes. The events also make the sequential mode scriptable from outside, a test harness or onboarding tracker can listen for next and previous to know exactly which step a user reached, without the tour library needing to report anywhere itself.

Editorial conclusion

Use chardin.js when an existing jQuery application needs lightweight, first-run style instructions without adopting a tour framework, since its data attribute model annotates elements in place and the two file footprint integrates anywhere jQuery runs. Choose a modern framework-free tour library for new non-jQuery projects. Before adopting, check the version history, one tagged release from February 2020 with the last push in June 2026, so treat it as stable and small rather than evolving, prefer the sequential mode attributes for multi-step flows, and keep overlay text in the JSON option when non-developers need to edit instructions without touching markup.

Frequently asked questions

Official sources

1. Issues
2. pablof7z/chardin.js on GitHub
3. Project website
4. README
5. Releases