ZarCanvas 🎨

---

ZarCanvas

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

---

🚀 Installation

npm install zarcanvas

---

🛠️ Usage Examples

1. 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);

---

2. 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();

---

3. 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();

---

4. 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();

---

5. Ship Card

Compare two profiles with a love percentage and themed icons.

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

Music Card (MusicCardOptions)

Property	Type	Required	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

Profile Card (ProfileCardOptions)

Property	Type	Required	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

Instagram Card (InstagramCardOptions)

Property	Type	Required	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()

X (Tweet) Card (TweetCardOptions)

Property	Type	Required	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

Ship Card (ShipCardOptions)

Property	Type	Required	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

Best Visual Results

• 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()..

---

📜 License

ISC © Muhammad Abuzar (ZarScape)