ZarCanvas

A native canvas library for creating modern, visually clean cards. Optimized for social media simulation and music player visuals.

NPM ISC License Node.js >=18 Discord GitHub

Installation

npm install zarcanvas

Usage Examples

01

Music Card

Perfect for "Now Playing" visuals with gradient support.

Full Version (With Progress)

import { MusicCard } from 'zarcanvas';
import fs from 'node:fs';

const card = new MusicCard({
  trackName: 'MONTAGEM ZAR',
  artistName: 'ZarScape',
  albumArt: 'https://raw.githubusercontent.com/ZarScape/ZarScape/refs/heads/main/images/ZarScape/logo-with-background.png',
  backgroundColor: '#082131ff',
  gradientColor: '#467ca0ff',
  progressBar: 75,
  progressTime: '2:30 / 3:12',
  trackNameColor: '#bacfddff',
  artistNameColor: '#abc2d1ff',
  progressTimeColor: '#9cb4c4ff',
  progressBarColor: ['#2a4a5aff', '#68b3d8']
});

const buffer = await card.build();
fs.writeFileSync('music_full.png', buffer);

Minimal Version (No Progress)

const minimalCard = new MusicCard({
  trackName: 'MONTAGEM ZAR',
  artistName: 'ZarScape',
  albumArt: 'https://raw.githubusercontent.com/ZarScape/ZarScape/refs/heads/main/images/ZarScape/logo-with-background.png',
  backgroundColor: '#082131ff',
  gradientColor: '#467ca0ff',
  trackNameColor: '#bacfddff',
  artistNameColor: '#abc2d1ff'
});

const buffer = await minimalCard.build();
fs.writeFileSync('music_minimal.png', buffer);

02

Profile Card

Designer profile card with background blur and frame effects.

import { ProfileCard } from 'zarcanvas';

const card = new ProfileCard({
  avatarURL: 'https://raw.githubusercontent.com/ZarScape/ZarScape/refs/heads/main/images/ZarScape/logo-with-background.png',
  decorationURL: 'https://cdn.discordapp.com/avatar-decoration-presets/a_64c339e0c128dcb279ae201b1190d9d3.png',
  backgroundURL: 'https://raw.githubusercontent.com/ZarScape/ZarScape/refs/heads/main/images/ZarScape/banner-with-text.png',
  userName: 'zarscape',
  userDisplayname: 'ZarScape',
  backgroundBlur: 20,
  usernameColor: '#b8e7ff',
  borderColor: ['#60a5c7', '#193542ff']
});

const buffer = await card.build();

03

Instagram Card

Authentic Instagram post simulation.

import { InstagramCard } from 'zarcanvas';

const card = new InstagramCard({
  username: "ZarScape",
  avatar: "https://raw.githubusercontent.com/ZarScape/ZarScape/refs/heads/main/images/ZarScape/logo-with-background.png",
  postImage: "https://raw.githubusercontent.com/ZarScape/ZarScape/refs/heads/main/images/ZarScape/logo-with-background.png",
  likeCount: 125000,
  verified: true,
  postDate: new Date(Date.now() - 86400000)
});

const buffer = await card.generate();

04

Tweet (X) Card

Native X/Twitter post simulation using Chirp fonts.

import { TweetCard } from 'zarcanvas';

const card = new TweetCard({
  user: { 
    displayName: 'Muhammad Abuzar', 
    username: 'zarscape' 
  },
  message: 'Testing X (tweet) card using ZarCanvas. Looks awesome! #ZarCanvas #Design #ZarScape',
  verified: true,
  stats: {
    replies: 124,
    retweets: 850,
    likes: '12K',
    views: '250K'
  }
});

const buffer = await card.build();

05

Ship Card

import { ShipCard } from 'zarcanvas';

const card = new ShipCard()
  .setAvatar1('https://raw.githubusercontent.com/ZarScape/ZarScape/refs/heads/main/images/ZarScape/logo-with-background.png')
  .setAvatar2('https://raw.githubusercontent.com/ZarScape/ZarScape/refs/heads/main/images/ZarScape/logo-with-background.png')
  .setPercentage(95);

const buffer = await card.build();

API Reference

MusicCardOptions

Property	Type	Description	Default
trackName	string	Title of the track.	-
artistName	string	Name of the artist.	-
albumArt	string	URL or path to artwork.	-
backgroundColor	string	Background hex/CSS color.	-
gradientColor	string	Color for decorative glow.	-
trackNameColor	string	Track title hex color.	#000000
artistNameColor	string	Artist name hex color.	#555555
progressBar	number	Percentage (0-100).	undefined
progressBarColor	string \| string[]	Solid or gradient color.	#000000
progressTime	string	Time text (e.g. "2:30 / 4:00").	undefined

ProfileCardOptions

Property	Type	Description	Default
avatarURL	string	Main profile avatar URL.	-
userName	string	The handle/username (with @).	-
userDisplayname	string	Large display title.	userName
backgroundBlur	number	Blur intensity (0-100).	20
usernameColor	string	Hex color for the title.	#b8e7ff
borderColor	string \| string[]	Solid or gradient border.	undefined
squareAvatar	boolean	Use square instead of circle avatar.	false

InstagramCardOptions

Property	Type	Description	Default
username	string	Instagram handle.	-
avatar	string	Profile image URL.	-
postImage	string	Main post content image URL.	-
likeCount	number	Total number of likes.	-
verified	boolean	Shows blue verified badge.	true
postDate	Date \| number	Date of the post.	Date.now()

TweetCardOptions

Property	Type	Description	Default
user	object	{ displayName: string, username: string }	-
message	string	The tweet content text.	-
stats	object	{ replies, retweets, likes, views }	-
verified	boolean	Shows blue checkmark badge.	true
timestamp	string	Relative time (e.g. "1h").	1h
avatar	string	Profile image URL.	ZarScape Logo

ShipCardOptions

Property	Type	Description	Default
avatar1	string	First user avatar URL.	-
avatar2	string	Second user avatar URL.	-
percentage	number	Love percentage (0-100).	-
background	string	Background image URL.	Default Gradient
font	string	Custom font family name.	Plus Jakarta Sans

Guide & Tips

Images: Use high-resolution square images for avatars to prevent stretching or warping.
Gradients: For properties accepting `string[]`, providing 2-3 hex codes creates a smooth professional linear transition.
Async Handling: All card generation methods are asynchronous. Always use `await` when calling `.build()` or `.generate()`.