@hunterchen/canvas

A React-based canvas library for creating pannable, zoomable, and interactive canvas experiences. Originally developed (by me) for the Hack Western 12 Website.

Installation

Install the package via npm:

npm install @hunterchen/canvas

Required Peer Dependencies

This library requires the following peer dependencies:

npm install react react-dom framer-motion

Important: Import Styles

You must import the compiled CSS file in your application's entry point. The library uses pre-compiled Tailwind CSS, so you don't need to install or configure Tailwind yourself.

Note: The library uses the canvas- prefix for all custom CSS classes and variables to minimize conflicts with your project. Custom colors like canvas-heavy, canvas-medium, canvas-offwhite, fonts like canvas-figtree, and utilities like canvas-backface-hidden are scoped to avoid naming collisions. You can safely use Tailwind CSS in your own project alongside this library.

In your main application file (e.g., App.tsx, _app.tsx, main.tsx, or index.tsx):

import '@hunterchen/canvas/styles.css';

For Next.js:

// pages/_app.tsx
import '@hunterchen/canvas/styles.css';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

For Vite/React:

// main.tsx or App.tsx
import '@hunterchen/canvas/styles.css';
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Quick Start

import { Canvas, CanvasComponent } from '@hunterchen/canvas';

const homeCoordinates = { x: 0, y: 0, width: 1920, height: 1080 };

function App() {
  return (
    <Canvas homeCoordinates={homeCoordinates}>
      <CanvasComponent offset={homeCoordinates}>
        {/* Your section content here */}
      </CanvasComponent>
    </Canvas>
  );
}

The Canvas component requires homeCoordinates to define the initial viewport position. Use CanvasComponent to wrap your content sections and position them at specific coordinates on the canvas.

Configuration

Home Coordinates

The homeCoordinates prop defines where the canvas initially centers when it loads. This is a required prop that specifies the starting section's position and dimensions:

const homeCoordinates: SectionCoordinates = {
  x: 2867,      // X position in canvas space
  y: 1200,      // Y position in canvas space
  width: 264,   // Section width
  height: 800   // Section height
};

<Canvas homeCoordinates={homeCoordinates}>
  {/* ... */}
</Canvas>

Navigation Items

The navItems prop is optional and defines sections that appear in the canvas navbar. Each navigation item specifies a section with its coordinates, label, icon, and whether it's the home section:

import type { NavItem } from '@hunterchen/canvas';

const navItems: NavItem[] = [
  {
    id: "home",
    label: "Home",
    icon: "Home",           // Lucide icon name or custom component
    x: 2867,
    y: 1200,
    width: 264,
    height: 800,
    isHome: true            // Marks this as the home section
  },
  {
    id: "about",
    label: "About",
    icon: "Info",
    x: 1400,
    y: 400,
    width: 1013,
    height: 800
  },
  // ... more sections
];

<Canvas homeCoordinates={homeCoordinates} navItems={navItems}>
  {/* ... */}
</Canvas>

When navItems is provided, the canvas will render a navbar with buttons to navigate between sections.

Using Icons

The icon property accepts either a Lucide icon name (string) or a custom React component:

import { Heart } from 'lucide-react';

// Using Lucide icon names (strings)
const navItems: NavItem[] = [
  { id: "home", label: "Home", icon: "Home", ...coordinates.home, isHome: true },
  { id: "about", label: "About", icon: "Info", ...coordinates.about },
];

// Using custom icon components
const CustomIcon = ({ className }: { className?: string }) => (
  <svg className={className} viewBox="0 0 24 24" fill="currentColor">
    <circle cx="12" cy="12" r="10" />
  </svg>
);

const navItems: NavItem[] = [
  { id: "home", label: "Home", icon: Heart, ...coordinates.home, isHome: true },
  { id: "custom", label: "Custom", icon: CustomIcon, ...coordinates.custom },
];

For Lucide icons, use the PascalCase icon name as a string (e.g., "Home", "Settings", "ChevronRight"). See the Lucide icons list for available icons.

Canvas Dimensions

By default, the canvas uses a size of 6000×4000 pixels. You can customize the canvas dimensions using the canvasWidth and canvasHeight props to create larger or smaller canvas spaces:

<Canvas
  homeCoordinates={homeCoordinates}
  canvasWidth={8000}   // Custom width (default: 6000)
  canvasHeight={6000}  // Custom height (default: 4000)
>
  {/* ... */}
</Canvas>

When to customize canvas dimensions:

Larger canvases (e.g., 10000×8000): When you have many sections spread across a wide area, or want more space for users to explore
Smaller canvases (e.g., 4000×3000): For simpler layouts with fewer sections, reducing memory usage on lower-end devices
Custom aspect ratios: Match your content layout needs (e.g., ultra-wide canvases for timeline-style layouts)

Important considerations:

Canvas coordinates in homeCoordinates, navItems, and CanvasComponent offsets should be within your custom canvas bounds
Larger canvases use more memory but provide more space for content
The canvas automatically handles zoom limits based on your custom dimensions

Customization

Background Customization

The canvas comes with neutral gray default backgrounds. You can fully customize the canvas background, intro/wrapper background, and intro content.

Canvas Background

The canvas background consists of a gradient, dot pattern, and noise filter. Customize it by passing a canvasBackground prop:

import { Canvas, DefaultCanvasBackground } from '@hunterchen/canvas';

// Option 1: Use the default component with custom props
<Canvas
  homeCoordinates={homeCoordinates}
  canvasBackground={
    <DefaultCanvasBackground
      gradientStyle="radial-gradient(circle, #ff6b6b 0%, #4ecdc4 100%)"
      dotColor="#333333"
      dotOpacity={0.5}
      showFilter={false}
    />
  }
>
  {/* ... */}
</Canvas>

// Option 2: Pass your own custom background component
<Canvas
  homeCoordinates={homeCoordinates}
  canvasBackground={<MyCustomBackground />}
>
  {/* ... */}
</Canvas>

DefaultCanvasBackground props:

Prop	Type	Default	Description
`gradientStyle`	`string`	neutral gray gradient	CSS gradient string
`showDots`	`boolean`	`true`	Show dot pattern overlay
`dotColor`	`string`	`#888888`	Dot pattern color
`dotSize`	`number`	`1.5`	Dot size in pixels
`dotSpacing`	`number`	`22`	Dot spacing in pixels
`dotOpacity`	`number`	`0.35`	Dot pattern opacity (0-1)
`showFilter`	`boolean`	`true`	Show noise filter
`filterOpacity`	`number`	`0.6`	Noise filter opacity (0-1)

Intro/Wrapper Background

Customize the background shown during the intro animation:

import { Canvas, DefaultWrapperBackground } from '@hunterchen/canvas';

// Option 1: Simple gradient string
<Canvas
  homeCoordinates={homeCoordinates}
  introBackgroundGradient="linear-gradient(to bottom, #667eea 0%, #764ba2 100%)"
>
  {/* ... */}
</Canvas>

// Option 2: Custom wrapper background component
<Canvas
  homeCoordinates={homeCoordinates}
  wrapperBackground={
    <DefaultWrapperBackground
      gradient="linear-gradient(to top, #FEB6AF 0%, #EAD2DF 50%)"
    />
  }
>
  {/* ... */}
</Canvas>

Intro Content

Customize the logo and title shown during loading:

import { Canvas, DefaultIntroContent } from '@hunterchen/canvas';

<Canvas
  homeCoordinates={homeCoordinates}
  introContent={
    <DefaultIntroContent
      logoSrc="/my-logo.svg"
      logoAlt="My App Logo"
      logoWidth={80}
      logoHeight={80}
      title="MY APP"
      titleClassName="text-blue-600"
    />
  }
  loadingText="Loading..."
>
  {/* ... */}
</Canvas>

Complete Theming Example (Hack Western Style)

Here's a complete example showing how to apply a custom theme with warm coral/lilac colors (used by Hack Western):

import {
  Canvas,
  DefaultCanvasBackground,
  DefaultIntroContent,
  DefaultWrapperBackground,
  canvasWidth,
  canvasHeight,
} from '@hunterchen/canvas';

// Hack Western theme colors (coral/lilac warm palette)
const CANVAS_GRADIENT = `radial-gradient(ellipse ${canvasWidth}px ${canvasHeight}px at ${canvasWidth / 2}px ${canvasHeight}px, #f7f1e5 0%, #d9c8e6 41%, #ffb5a7 59%, #f7f1e5 90%)`;
const INTRO_GRADIENT = "linear-gradient(to top, #ffb5a7 0%, #d9c8e6 50%, #f7f1e5 100%)";
const BOX_GRADIENT = "radial-gradient(130.38% 95% at 50.03% 97.25%, #ffb5a7 0%, #d9c8e6 48.09%, #f7f1e5 100%)";

function App() {
  return (
    <Canvas
      homeCoordinates={homeCoordinates}
      navItems={navItems}
      introBackgroundGradient={INTRO_GRADIENT}
      canvasBoxGradient={BOX_GRADIENT}
      introContent={
        <DefaultIntroContent
          logoSrc="/logo.svg"
          logoAlt="Logo"
          title="HACK WESTERN"
          titleClassName="text-[#513b7a]"
        />
      }
      loadingText="LOADING..."
      canvasBackground={
        <DefaultCanvasBackground
          gradientStyle={CANVAS_GRADIENT}
          dotColor="#c9a7db"
        />
      }
      wrapperBackground={
        <DefaultWrapperBackground gradient={INTRO_GRADIENT} />
      }
      navbarConfig={{
        buttonConfig: {
          activeClassName: "bg-[#f5f2f7]",
          hoverClassName: "bg-[#f5f2f7]",
        },
      }}
    >
      {/* Your canvas content */}
    </Canvas>
  );
}

Customizing CSS Variables

The library uses CSS variables for theming. You can override them in your CSS to customize colors globally:

:root {
  /* Text colors */
  --canvas-heavy: #3c204c;      /* Darkest text */
  --canvas-emphasis: #513b7a;   /* Emphasized text */
  --canvas-active: #8f57ad;     /* Active/selected state */
  --canvas-medium: #776780;     /* Medium text */
  --canvas-light: #c3b8cb;      /* Light text */

  /* Background colors */
  --canvas-beige: #f7f1e5;      /* Warm beige */
  --canvas-coral: #ffb5a7;      /* Coral accent */
  --canvas-lilac: #d9c8e6;      /* Lilac accent */
  --canvas-salmon: #ffa585;     /* Salmon accent */
  --canvas-tinted: #c9a7db;     /* Tinted purple */
  --canvas-faint-lilac: #f5f2f7; /* Very light lilac */
  --canvas-offwhite: #fdfcfd;   /* Off-white */
  --canvas-highlight: #f5f2f7;  /* Highlight/hover */
}

Toolbar Customization

The toolbar displays the current canvas coordinates and zoom level. You can customize its position, appearance, and behavior using the toolbarConfig prop.

<Canvas
  homeCoordinates={homeCoordinates}
  toolbarConfig={{
    position: "top-right",
    className: "font-sans",
    style: { fontSize: "14px", color: "#525252" },
  }}
>
  {/* ... */}
</Canvas>

ToolbarConfig options:

Prop	Type	Default	Description
`hidden`	`boolean`	`false`	Hide the toolbar entirely
`display`	`'coordinates' \| 'scale' \| 'both'`	`'both'`	What to display
`position`	`'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`	`'top-left'`	Preset position
`disableAutoHide`	`boolean`	`false`	Disable auto-hide when at home position
`className`	`string`	-	Additional CSS classes for the container
`coordinatesClassName`	`string`	-	CSS classes for coordinates text
`scaleClassName`	`string`	-	CSS classes for scale text
`separatorClassName`	`string`	-	CSS classes for the separator
`style`	`CSSProperties`	-	Inline styles for the container
`coordinatesStyle`	`CSSProperties`	-	Inline styles for coordinates
`scaleStyle`	`CSSProperties`	-	Inline styles for scale
`separator`	`string`	`'\|'`	Custom separator character
`separatorGap`	`number \| string`	-	Gap around the separator (e.g., `8` or `'0.5rem'`)
`coordinatesFormat`	`(x: number, y: number) => string`	-	Custom coordinates formatter
`scaleFormat`	`(scale: number) => string`	-	Custom scale formatter

Toolbar Examples

// Show only scale, positioned bottom-right
<Canvas
  toolbarConfig={{
    display: "scale",
    position: "bottom-right",
  }}
/>

// Custom styling with Tailwind
<Canvas
  toolbarConfig={{
    position: "top-right",
    className: "font-sans font-medium px-4",
    separatorGap: 8,
    style: {
      color: "#525252",
      backgroundColor: "#fafafa",
      borderColor: "#d4d4d4",
    },
  }}
/>

// Custom formatters
<Canvas
  toolbarConfig={{
    coordinatesFormat: (x, y) => `X: ${x} Y: ${y}`,
    scaleFormat: (s) => `${(s * 100).toFixed(0)}%`,
    separator: "•",
    separatorGap: 12,
  }}
/>

// Custom position using style
<Canvas
  toolbarConfig={{
    style: {
      top: "50%",
      left: "20px",
      transform: "translateY(-50%)",
    },
  }}
/>

// Hide toolbar
<Canvas toolbarConfig={{ hidden: true }} />

Navbar Customization

The navbar provides navigation buttons to jump between canvas sections. You can customize its position, display mode, button styling, and tooltips using the navbarConfig prop.

<Canvas
  homeCoordinates={homeCoordinates}
  navItems={navItems}
  navbarConfig={{
    position: "top",
    display: "icons-labels",
  }}
>
  {/* ... */}
</Canvas>

NavbarConfig options:

Prop	Type	Default	Description
`hidden`	`boolean`	`false`	Hide the navbar entirely
`display`	`'icons' \| 'labels' \| 'icons-labels' \| 'compact'`	`'icons'`	Display mode for items
`position`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'bottom'`	Navbar position
`className`	`string`	-	Additional CSS classes for container
`style`	`CSSProperties`	-	Inline styles for container
`buttonConfig`	`NavbarButtonConfig`	-	Button styling options (see below)
`tooltipConfig`	`NavbarTooltipConfig`	-	Tooltip options (see below)
`gap`	`number`	`4`	Gap between buttons in pixels
`padding`	`number`	`4`	Padding inside navbar in pixels

NavbarButtonConfig options:

Prop	Type	Description
`className`	`string`	Additional classes for all buttons
`style`	`CSSProperties`	Inline styles for all buttons
`activeClassName`	`string`	Classes for active/pushed state
`activeStyle`	`CSSProperties`	Styles for active state
`hoverClassName`	`string`	Classes for hover state
`hoverStyle`	`CSSProperties`	Styles for hover state
`iconClassName`	`string`	Classes for icons
`iconSize`	`number`	Icon size in pixels (default: 20)
`labelClassName`	`string`	Classes for labels
`labelStyle`	`CSSProperties`	Styles for labels

NavbarTooltipConfig options:

Prop	Type	Default	Description
`disabled`	`boolean`	`false`	Disable tooltips entirely
`className`	`string`	-	Additional classes for tooltip
`style`	`CSSProperties`	-	Inline styles for tooltip
`delay`	`number`	`100`	Delay before showing tooltip (ms)

Display Modes

icons (default): Shows icons only, expands to show label when active, tooltip on hover
labels: Shows labels only, no icons
icons-labels: Always shows both icon and label for all items
compact: Icons only, no expansion on active, just highlights

Navbar Examples

// Position at top
<Canvas navbarConfig={{ position: "top" }} />

// Labels only (no icons)
<Canvas navbarConfig={{ display: "labels" }} />

// Always show icons + labels
<Canvas navbarConfig={{ display: "icons-labels" }} />

// Compact mode (icons only, no expansion)
<Canvas navbarConfig={{ display: "compact" }} />

// Custom container styling
<Canvas
  navbarConfig={{
    className: "bg-black/80 backdrop-blur-md",
    style: { borderRadius: "20px" },
  }}
/>

// Custom button styling
<Canvas
  navbarConfig={{
    buttonConfig: {
      activeClassName: "bg-blue-500",
      activeStyle: { color: "white" },
      hoverClassName: "bg-gray-100",
      iconSize: 24,
    },
  }}
/>

// Disable tooltips
<Canvas navbarConfig={{ tooltipConfig: { disabled: true } }} />

// Vertical sidebar layout
<Canvas navbarConfig={{ position: "left" }} />

// Hide navbar entirely
<Canvas navbarConfig={{ hidden: true }} />

Exported Constants

The library exports default gradient values you can use as a starting point:

import {
  DEFAULT_CANVAS_GRADIENT,    // Default canvas background gradient
  DEFAULT_INTRO_GRADIENT,     // Default intro background gradient
  DEFAULT_CANVAS_BOX_GRADIENT // Default blur mask gradient
} from '@hunterchen/canvas';

Usage Examples

Basic Canvas with Draggable Elements

import {
  Canvas,
  CanvasProvider,
  Draggable,
  CanvasToolbar,
  CanvasNavbar
} from '@hunterchen/canvas';

function MyCanvas() {
  return (
    <CanvasProvider>
      <Canvas>
        <CanvasToolbar />
        <CanvasNavbar />
        <Draggable initialX={100} initialY={100}>
          <div>Drag me!</div>
        </Draggable>
      </Canvas>
    </CanvasProvider>
  );
}

Development

To build the library from source:

# Install dependencies
npm install

# Build the library
npm run build

# Run type checking
npm run type-check

Key Features

Pan & Zoom: Click and drag to pan, pinch/scroll to zoom
Draggable Elements: Built-in support for draggable components
Performance Optimized (more to do): Adaptive rendering based on device capabilities
Pre-compiled CSS: No Tailwind configuration needed in your project
TypeScript Support: Full type definitions included

Available Exports

Components

Canvas - Main canvas component with pan/zoom functionality
CanvasWrapper - Animated wrapper for canvas initialization
CanvasComponent - Canvas component renderer with visibility optimization
Draggable, DraggableImage - Draggable elements
CanvasToolbar - Coordinate/zoom display toolbar
CanvasNavbar - Navigation buttons

Background Components

DefaultCanvasBackground - Customizable canvas background with gradient, dots, and filter
DefaultWrapperBackground - Customizable intro/wrapper background
DefaultIntroContent - Customizable intro logo and title
DEFAULT_CANVAS_GRADIENT - Default canvas gradient constant
DEFAULT_INTRO_GRADIENT - Default intro gradient constant
DEFAULT_CANVAS_BOX_GRADIENT - Default blur mask gradient constant

Contexts

CanvasProvider - Canvas state context provider
useCanvasContext - Hook to access canvas context
PerformanceProvider - Performance optimization context
usePerformanceMode, usePerformance - Performance-related hooks

Hooks

useWindowDimensions - Window size tracking
usePerformanceModeLegacy - Legacy performance optimization

Utilities

cn - Tailwind class merging utility (uses clsx + tailwind-merge)
Canvas utility functions (pan, zoom, coordinates)
Performance detection utilities
Constants and types

Types

ToolbarConfig - Toolbar customization options
ToolbarPosition - Preset toolbar positions
ToolbarDisplayMode - Toolbar display modes
NavbarConfig - Navbar customization options
NavbarPosition - Preset navbar positions
NavbarDisplayMode - Navbar display modes
NavbarButtonConfig - Navbar button styling options
NavbarTooltipConfig - Navbar tooltip options
NavItem - Navigation item configuration
SectionCoordinates - Section coordinate definition

API Reference

Canvas Props

The Canvas component accepts the following props:

Prop	Type	Required	Default	Description
`homeCoordinates`	`SectionCoordinates`	Yes	-	Initial viewport position and home section
`children`	`ReactNode`	Yes	-	Canvas content (typically `CanvasComponent` elements)
`canvasWidth`	`number`	No	`6000`	Total canvas width in pixels
`canvasHeight`	`number`	No	`4000`	Total canvas height in pixels
`navItems`	`NavItem[]`	No	-	Navigation items for navbar
`skipIntro`	`boolean`	No	`false`	Skip intro animation
`introContent`	`ReactNode`	No	-	Custom intro content during loading
`loadingText`	`string`	No	-	Custom loading text
`introBackgroundGradient`	`string`	No	-	Background gradient for intro
`canvasBoxGradient`	`string`	No	-	Canvas box gradient during intro
`growTransition`	`Transition`	No	-	Custom grow transition (Framer Motion)
`blurTransition`	`Transition`	No	-	Custom blur transition (Framer Motion)
`canvasBackground`	`ReactNode`	No	`<DefaultCanvasBackground />`	Custom canvas background
`wrapperBackground`	`ReactNode`	No	-	Custom wrapper/intro background
`toolbarConfig`	`ToolbarConfig`	No	-	Toolbar customization options
`navbarConfig`	`NavbarConfig`	No	-	Navbar customization options

NavItem Props

Each item in the navItems array has the following properties:

Prop	Type	Required	Description
`id`	`string`	Yes	Unique identifier for this section
`label`	`string`	Yes	Display label shown in the navbar
`icon`	`string \| React.ComponentType`	Yes	Lucide icon name or custom component
`x`	`number`	Yes	X coordinate on the canvas
`y`	`number`	Yes	Y coordinate on the canvas
`width`	`number`	Yes	Section viewport width
`height`	`number`	Yes	Section viewport height
`isHome`	`boolean`	No	If true, clicking triggers reset/home behavior

Draggable Props

interface DraggableProps {
  initialX?: number;
  initialY?: number;
  children: React.ReactNode;
}

CanvasContext

Access canvas state using useCanvasContext():

const { x, y, scale } = useCanvasContext();

Library Structure

@hunterchen/canvas/
├── dist/
│   ├── styles.css          # Pre-compiled Tailwind CSS (import this!)
│   ├── index.js            # Main entry point
│   ├── index.d.ts          # TypeScript definitions
│   ├── components/         # Canvas components
│   ├── contexts/           # React contexts
│   ├── hooks/              # Custom hooks
│   └── lib/                # Utility functions
└── src/
    ├── components/
    ├── contexts/
    ├── hooks/
    ├── lib/
    └── styles.css          # Source CSS file

Troubleshooting

Styles Not Working

Make sure you've imported the CSS file:

import '@hunterchen/canvas/styles.css';

TypeScript Errors

Ensure you have the required peer dependencies installed:

npm install react react-dom framer-motion

Missing Types

The library includes full TypeScript definitions. If you're having issues, make sure your tsconfig.json includes:

{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

License

MIT

Contributing

This library was extracted from the Hack Western 12 Website. Contributions are welcome!

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github/workflows		.github/workflows
examples		examples
src		src
.eslintrc.json		.eslintrc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
claude.md		claude.md
package-lock.json		package-lock.json
package.json		package.json
pnpm-workspace.yaml		pnpm-workspace.yaml
release-please-config.json		release-please-config.json
rolldown.config.ts		rolldown.config.ts
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

License

hunterchen7/canvas

Folders and files

Latest commit

History

Repository files navigation

@hunterchen/canvas

Installation

Required Peer Dependencies

Important: Import Styles

Quick Start

Configuration

Home Coordinates

Navigation Items

Using Icons

Canvas Dimensions

Customization

Background Customization

Canvas Background

Intro/Wrapper Background

Intro Content

Complete Theming Example (Hack Western Style)

Customizing CSS Variables

Toolbar Customization

Toolbar Examples

Navbar Customization

Display Modes

Navbar Examples

Exported Constants

Usage Examples

Basic Canvas with Draggable Elements

Development

Key Features

Available Exports

Components

Background Components

Contexts

Hooks

Utilities

Types

API Reference

Canvas Props

NavItem Props

Draggable Props

CanvasContext

Library Structure

Troubleshooting

Styles Not Working

TypeScript Errors

Missing Types

License

Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Contributors 4

Uh oh!

Languages

Packages