Lettercrap is a JavaScript library that uses an image mask to generate dynamic ASCII art on the web. It looks like this:
To use the library in the browser, include both lettercrap.min.js and lettercrap.min.css as follows:
<!doctype html>
<html lang="en">
<head>
<title />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.css" />
</head>
<body>
<!-- TARGETED ELEMENTS GO HERE -->
<script type="module">
import * as Lettercrap from 'https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.js';
// CODE THAT USES THE LIBRARY GOES HERE
</script>
</body>
</html>The JS file exports some functions you can use to generate ASCII art. You can define the data holders (and subsequent rendering sections) in your HTML in one of two ways:
-
Create a
<div>with thedata-lettercrapattribute and set the value to the source of a black-and-white image.<div data-lettercrap="example.png"></div>
-
Create a
<div>with thedata-lettercrap-textattribute and set the value to the text you want to generate the ASCII art from.<div data-lettercrap-text="LETTERCRAP"></div>
For initializing elements on the page, you can use one of three functions:
-
Initialize a single element by passing its
Nodeto theinitElementfunction ofLettercrap:<script type="module"> import * as Lettercrap from 'https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.js'; const element = document.getElementById('...'); Lettercrap.initElement(element); </script>
-
Initialize multiple elements by passing a
NodeListto theinitElementsfunction ofLettercrap:<script type="module"> import * as Lettercrap from 'https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.js'; const elements = document.querySelectorAll('...'); Lettercrap.initElements(elements); </script>
-
Initialize all elements on the page by calling the
initfunction ofLettercrap:<script type="module"> import * as Lettercrap from 'https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.js'; Lettercrap.init(); </script>
For resetting initialized elements, you can use one of three functions:
-
Reset a single element by passing its
Nodeto theresetElementfunction ofLettercrap:<script type="module"> import * as Lettercrap from 'https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.js'; const element = document.getElementById('...'); Lettercrap.resetElement(element); </script>
-
Reset multiple elements by passing a
NodeListto theresetElementsfunction ofLettercrap:<script type="module"> import * as Lettercrap from 'https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.js'; const elements = document.querySelectorAll('...'); Lettercrap.resetElements(elements); </script>
-
Reset all elements on the page by calling the
resetfunction ofLettercrap:<script type="module"> import * as Lettercrap from 'https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.js'; Lettercrap.reset(); </script>
Although the library comes pre-configured with a set of default settings, we provide further means for customizing the output on a per-element basis:
-
By default,
0and1are used to fill in the shape of your image or text. You can change the set of symbols used with thedata-lettercrap-lettersattribute:<div data-lettercrap="example.png" data-lettercrap-letters="ABC"></div>
-
To throw in the occasional full word into the mix, you can specify a space-delimited string of words to choose from using the
data-lettercrap-wordsattribute:<div data-lettercrap="example.png" data-lettercrap-words="APPLE BANANA CHERRY"></div>
-
You can change the time interval in milliseconds between updates to the ASCII art with the
data-lettercrap-update-intervalattribute (default is150):<div data-lettercrap="example.png" data-lettercrap-interval="200"></div>
-
When using
data-lettercrap-text, you can set the font of the generated ASCII art with thedata-lettercrap-font-familyattribute (default ismonospace):<div data-lettercrap-text="LETTERCRAP" data-lettercrap-font-family="times"></div>
-
When using
data-lettercrap-text, you can set the font weight of the generated ASCII art with thedata-lettercrap-font-weightattribute (default isnormal):<div data-lettercrap-text="LETTERCRAP" data-lettercrap-font-weight="bold"></div>
You can also configure how the library behaves by using the exported configure function to overwrite the default options:
<script type="module">
import * as Lettercrap from 'https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.js';
Lettercrap.configure({ letters: 'AB' });
Lettercrap.init();
</script>The following table shows the correspondence between the global Config properties and the per-instance data equivalents:
Global Config property |
Per-instance data equivalent |
Accepted values |
|---|---|---|
content |
data-lettercrap |
Non-blank string |
letters |
data-lettercrap-letters |
Non-blank string |
words |
data-lettercrap-words |
Non-blank string array |
font_family |
data-lettercrap-font-family |
font-family |
font_weight |
data-lettercrap-font-weight |
font-weight |
update_interval |
data-lettercrap-interval |
Positive integer or zero |
Please note that changes to default options will not propagate to instances that have already been rendered.
To synchronize the rendered instances that rely on default settings, you can call the refresh function:
<script type="module">
import * as Lettercrap from 'https://cdn.jsdelivr.net/npm/@lettercrap/web/dist/lettercrap.min.js';
Lettercrap.init().then(async () => {
Lettercrap.configure({ letters: 'AB' });
return Lettercrap.refresh();
});
</script>Check out the example to see how this all fits together.
To get the example working locally, you can run:
npm run devThis will start a local HTTP server on port 8080.
If you have ideas for a feature you would like to see implemented or if you have any questions, we encourage you to create a new discussion. By initiating a discussion, you can engage with the community and our team, and we'll respond promptly to address your queries or consider your feature requests.
To report any issues or bugs you encounter, please create a new issue. Providing detailed information about the problem you're facing will help us understand and address it more effectively. Rest assured, we are committed to promptly reviewing and responding to the issues you raise, working collaboratively to resolve any bugs and improve the overall user experience.
Please refer to CONTRIBUTING.md for more information.