Core text-to-ASCII conversion functionality providing both synchronous and asynchronous APIs with comprehensive font and layout control options.
The primary figlet function, which is an alias for figlet.text().
/**
* Converts text to ASCII art using specified font and options
* @param text - Text string to convert to ASCII art
* @param options - Font and layout options (object) or font name (string)
* @param callback - Optional callback function (err, result) => void
* @returns Promise<string> - ASCII art string
*/
function figlet(text, options, callback);Usage Examples:
const figlet = require("figlet");
// With callback
figlet("Hello", (err, data) => {
if (err) console.error(err);
else console.log(data);
});
// With options object
figlet("Hello", { font: "Ghost", width: 80 }, (err, data) => {
console.log(data);
});
// With font name string
figlet("Hello", "Big", (err, data) => {
console.log(data);
});
// Promise-based (no callback)
figlet("Hello")
.then(data => console.log(data))
.catch(err => console.error(err));Asynchronous text-to-ASCII conversion with Promise and callback support.
/**
* Asynchronously converts text to ASCII art
* @param text - Text string to convert
* @param options - Configuration options or font name string
* @param callback - Optional callback function
* @returns Promise<string> - Generated ASCII art
*/
function text(text, options, callback);Usage Examples:
// Promise with async/await
const result = await figlet.text("Welcome", {
font: "Standard",
horizontalLayout: "fitted",
width: 120
});
// Complex layout options
const art = await figlet.text("FIGlet", {
font: "Big",
horizontalLayout: "controlled smushing",
verticalLayout: "fitted",
printDirection: 0,
showHardBlanks: false
});
// Multiline text with wrapping
const wrapped = await figlet.text("This is a very long line that will wrap", {
font: "Standard",
width: 40,
whitespaceBreak: true
});Synchronous text conversion (Node.js only - not available in browser environments).
/**
* Synchronously converts text to ASCII art (Node.js only)
* @param text - Text string to convert
* @param options - Configuration options or font name string
* @returns string - Generated ASCII art
* @throws Error if font loading fails or invalid options
*/
function textSync(text, options);Usage Examples:
// Basic synchronous usage
const result = figlet.textSync("Hello", "Standard");
// With options
const art = figlet.textSync("Node.js", {
font: "Ghost",
horizontalLayout: "full"
});
// Error handling
try {
const result = figlet.textSync("Test", { font: "NonExistentFont" });
} catch (err) {
console.error("Font loading failed:", err.message);
}Control how characters are positioned and spaced:
horizontalLayout - Character spacing behavior:
"default" - Use font's default horizontal rules"full" - Full width, no character overlap"fitted" - Characters touch but don't overlap"controlled smushing" - Apply all smushing rules"universal smushing" - Override all character overlapsverticalLayout - Line spacing behavior:
"default" - Use font's default vertical rules"full" - Full height between lines"fitted" - Lines touch but don't overlap"controlled smushing" - Apply vertical smushing rules"universal smushing" - Override all line overlapsControl text flow and line breaking:
width (number) - Maximum line width in characters (-1 for unlimited)whitespaceBreak (boolean) - Enable intelligent word wrapping at whitespace boundariesControl text rendering and direction:
printDirection (number) - Text direction (0 = left-to-right, 1 = right-to-left)showHardBlanks (boolean) - Show hard blank characters instead of spacesText generation functions may throw or reject with:
// Async error handling
figlet.text("Hello", { font: "InvalidFont" })
.catch(err => {
console.error("Generation failed:", err.message);
});
// Sync error handling
try {
const result = figlet.textSync("Hello", { width: "invalid" });
} catch (err) {
console.error("Invalid width option:", err);
}