KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

Tinseltown.js

★ 119 Open GitHub ↗

A lightweight CSS/JS library for faux hacker-movie-style page loading effects

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Tinseltown.js

> ⚠️ v2.0.0 is ready, but not yet published to npm. Consider it a work in progress. Built versions - dist/tinseltown.umd.min.js and dist/tinseltown.min.css - are ready for use.

Tinseltown is a small (< 4KB) JS and CSS front-end library to add faux flicker loading effects, a la Hollywood hacker movies, to various elements on a web page.

**Visit [the website](http://antrikshy.github.io/Tinseltown.js) for a demo.** Or clone this repo and take a look at `examples/basic.html`.

Tinseltown uses CSS animations for the effects themselves, but needs to have a small JavaScript component (< 1KB) to actually make it work. What makes these effects work is randomness. When the animations aresec initiated, they are given random `animation-delay` values as offsets; otherwise they would all play in sync, invalidating the purpose.

## Getting Started

The **easiest method** is to simply drop the compiled tinseltown.umd.min.js and tinseltown.min.css files from the root folder of this repo into the front-end of whatever web project you are working on. You can now skip to the [Usage](#usage) section and use everything as-is.

For a more modern install into a project that's built on Node using a bundler:

```
npm install --save Tinseltown.js
```

### Module Imports

To integrate Tinseltown.js into modern front-end development, the method depends on whether you are using a bundler (like Webpack, Rollup, or Vite) or a direct script tag. **The package ships both an ESM build (`tinseltown.esm.min.js`) and a UMD build (`tinseltown.umd.min.js`).**

#### 1. ES Modules (ESM) - Recommended
Use this method if your project supports standard JavaScript modules (using `import`/`export`).

```javascript
import Tinseltown from 'tinseltown/tinseltown.esm.min.js';
Tinseltown.tnslInit();
```

#### 2. CommonJS (Node.js/RequireJS)
Use this method in older module environments that rely on `require()`.

```javascript
const Tinseltown = require('tinseltown');
Tinseltown.tnslInit();
```

#### 3. Legacy/Vanilla JavaScript (Global Scope / UMD)
For projects that do not use a bundler, download the .umd.min.js and .min.css files directly, place them somewhere in your project, and use `script` and `link` tags to reference them.

```javascript
document.addEventListener('DOMContentLoaded', () => {
    Tinseltown.tnslInit();
});
```

### Customizing Animation Timings (Advanced)

It is possible to use Sass variables to customize animation timings if you want to dive deeper and only use this library for its randomization features.

In your Sass file, set any of the variables in the following example to CSS time values of your choice *before* importing tinseltown.min.css.

```scss
$tnsl-flicker-duration: 1s;             // default 0.5s
$tnsl-flickerQuick-duration: 0.5s;      // default 0.2s
$tnsl-slideFromLeft-duration: 0.2s;     // default 0.1s
$tnsl-slideFromRight-duration: 0.2s;    // default 0.1s

@import 'tinseltown.scss'               // place *after* overriden variables
```

> **Note:** The default values above were chosen to look good when used with the default `maxDelay` value of 1 second and vice versa.

Of course, feel free to **download the tinseltown.scss file directly** from the src folder in this repo and place it in your project.

## Usage

Once the JS and CSS files are available to use in your project's front-end, use the following CSS classes to set animations.

```
.tnsl-flicker            /* standard Hollywood-style flicker effect */
.tnsl-flickerQuick       /* shorter variant of flicker */
.tnsl-slideFromLeft      /* quick slide from left (using translate3d(-100%, 0, 0)) */
.tnsl-slideFromRight     /* quick slide from right (using translate3d(100%, 0, 0)) */
```

In many cases, however, your design may benefit from some randomness. This is why a special, random animation class is included as well.

```
.tnsl-random
```

When you trigger the basic case (described in the [next section](#basic-trigger)), all elements with the `tnsl-random` class are first randomly assigned one of the above animation classes before playing. Every time the page loads, your `tnsl-random` classes may get a different set of effects.

### Basic Trigger

Once you are ready to trigger the animations, call

```javascript
tnslInit([maxDelay])
```

where `maxDelay` is the longest time (in seconds) that you want to allow any single `animation-delay` value to be.

This means that the *start* of each effect will be between `0` and `maxDelay` seconds from when the function is called. This does *not* guarantee that all the effects *will* be spread across the first `maxDelay` seconds, because randomness can still cause them to bunch up and trigger in the first second... or even half that.

You can omit the argument if you want, and a default of 1 second will be used.

> **Note:** The default animation timings in the compiled CSS were tuned to look good when used with the default `maxDelay` value of 1 second and vice versa.

If you want to trigger the animations at page load time, simply use

```javascript
window.onload = function() { tnslInit(); }      // without jQuery
$(document).ready(function() { tnslInit(); });  // with jQuery
```

or otherwise add the function call to whatever handles your page load scripts.

### More Granular Control (Advanced)

If you want more granular control over the animations on your page, you can use some convenient utility functions included in Tinseltown.

#### `tnslReplaceRandom([animations])`

Processes all elements that have the `tnsl-random` class, assigning them random animations.

Optionally provide it an array of animation names, esp. if you do not want it to assign a certain animation or two. Pick from strings `flicker`, `flickerQuick`, `slideFromLeft` and `slideFromRight`. All animations used if no argument given.

> **Note:** It's highly recommended that you process any `tnsl-random` elements before calling animation functions, or they will simply not be animated. Calling animation trigger functions before *and* after processing all randoms may cause all animations to play twice, unless you perform JavaScript trickery to prevent this.

#### The **`maxDelay`** argument

For info on the optional `maxDelay` argument accepted by the following functions, refer to the [Basic Trigger](#basic-trigger) section.

#### `tnslPlayFlicker([maxDelay])`

Triggers all `flicker` animations.

#### `tnslPlayFlickerQuick([maxDelay])`

Triggers all `flickerQuick` animations.

#### `tnslPlaySlideFromLeft([maxDelay])`

Triggers all `slideFromLeft` animations.

#### `tnslPlaySlideFromRight([maxDelay])`

Triggers all `slideFromRight` animations.

#### `tnslPlayAllFlicker([maxDelay])`

Triggers all `flicker` and `flickerQuick` animations.

#### `tnslPlayAllSlide([maxDelay])`

Triggers all `slideFromLeft` and `slideFromRight` animations.

#### `tnslPlayAll([maxDelay])`

Triggers all animations.

#### `tnslInit([maxDelay])`

Processes all `tnsl-random` elements *and* triggers all animations.

## Contribute

Tinseltown.js could use some help. If you find issues, or just want to contribute improvements, feel free to clone, modify, **test** and send pull requests. When developing locally:

1. Have Node.js and npm installed.
2. Clone this repo and run `npm install` at the top level.
3. Edit src/tinseltown.js and src/tinseltown.scss.
4. Run `npm run build` to build tinseltown.*.min.js and tinseltown.min.css files into the dist folder. Optionally, run `npx gulp watch` to update the minified files as you make your edits in src.
5. Open example/basic.html in your browser or import these minified files into your own local HTML file to test visually.

You can contact me via [Reddit Chat](https://reddit.com/u/Antrikshy).

### Potential Features

1. **Add support for scrolling.** It would be nice to either support scroll-activated animation triggers natively, or at least allow users to trigger all animations inside a supplied DOM element, so that they can set it up themselves.
2. Maybe allow users to select a random flicker animation only or slide animation only.
3. Come up with more hacker-style CSS animations.

Tinseltown.js

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README