fabric-layers-react

A fabric.js coordinate-plane (grid) & layers library for React applications.

Important: This library now depends on the fabric-layers core library. Please see the Migration Guide for details on updating from previous versions.

Features

• Coordinate Plane System: Create interactive canvases with precise coordinate systems
• Grid System: Customizable grid with labels, colors, and spacing options
• Layer Management: Easily add, remove, and organize multiple canvas layers
• Vector Drawing Tools: Draw shapes, lines, and markers with built-in vector components
• Image Support: Display and manipulate images on canvas
• Measurement Tools: Measure distances and areas on your canvas
• Full TypeScript Support: Comprehensive type definitions for all components

Installation

Using npm

# First ensure you're using the correct Node version
nvm use

# Install the packages
npm install fabric-layers fabric-layers-react fabric-pure-browser react

Using yarn

# First ensure you're using the correct Node version
nvm use

# Install the packages
yarn add fabric-layers fabric-layers-react fabric-pure-browser react

Architecture

The library is now split into two packages:

1. fabric-layers - Core functionality without React dependencies

   • Contains all core utilities, constants, geometry tools, grid fundamentals
   • No React-specific code or dependencies
   • Can be used independently in any JavaScript project

2. fabric-layers-react - React extensions

   • Depends on the fabric-layers core library
   • Contains all React components, hooks, and JSX rendering
   • Provides React-specific implementation on top of core functionality

For most users, you can continue to import React components from fabric-layers-react as before. For advanced users who need direct access to core functionality, you can now import from either library depending on your needs.

// Import React components from fabric-layers-react
import { CanvasLayer, useGridContext } from 'fabric-layers-react';

// Import core functionality directly from fabric-layers
import { GridManager, Point, Constants } from 'fabric-layers';

This separation allows for:

• Using the core functionality without React dependencies
• Better code organization and maintenance
• More flexibility for different frameworks
• Smaller bundle sizes when only core functionality is needed

Basic Usage

Create a Coordinate Plane

import React, { useEffect, useRef } from 'react';
import { CoordinatePlane } from 'fabric-layers-react';

function MyCanvas() {
  const containerRef = useRef(null);
  const planeRef = useRef(null);
  
  useEffect(() => {
    if (containerRef.current && !planeRef.current) {
      // Create coordinate plane
      planeRef.current = new CoordinatePlane(containerRef.current, {
        gridEnabled: true,
        zoomEnabled: true,
        selectEnabled: true
      });
    }
    
    return () => {
      // Clean up
      if (planeRef.current) {
        // Handle cleanup if needed
      }
    };
  }, []);
  
  return (
    <div ref={containerRef} style={{ width: '100%', height: '500px' }} />
  );
}

Add Layers to Your Coordinate Plane

import React, { useEffect, useRef } from 'react';
import { CoordinatePlane, ImageLayer, Polyline } from 'fabric-layers-react';

function MyLayeredCanvas() {
  const containerRef = useRef(null);
  const planeRef = useRef(null);
  
  useEffect(() => {
    if (containerRef.current && !planeRef.current) {
      // Create coordinate plane
      const plane = new CoordinatePlane(containerRef.current, {
        gridEnabled: true
      });
      planeRef.current = plane;
      
      // Add an image layer
      const image = new ImageLayer({
        url: 'path/to/image.png',
        position: { x: 0, y: 0 },
        width: 500,
        height: 300
      });
      
      // Add a shape layer
      const path = new Polyline({
        points: [
          { x: 10, y: 10 },
          { x: 100, y: 50 },
          { x: 200, y: 10 }
        ],
        strokeColor: '#ff0000',
        strokeWidth: 2
      });
      
      // Add layers to the coordinate plane
      plane.addLayer(image);
      plane.addLayer(path);
    }
  }, []);
  
  return (
    <div ref={containerRef} style={{ width: '100%', height: '500px' }} />
  );
}

Customize the Grid

import React, { useEffect, useRef } from 'react';
import { CoordinatePlane, GridManager } from 'fabric-layers-react';

function CustomGrid() {
  const containerRef = useRef(null);
  
  useEffect(() => {
    if (containerRef.current) {
      // Create coordinate plane
      const plane = new CoordinatePlane(containerRef.current);
      
      // Create a grid manager
      const gridManager = new GridManager({
        coordinatePlane: plane,
        spacing: 20,
        color: '#0099cc',
        opacity: 0.4,
        showLabels: true
      });
      
      // Customize the grid
      gridManager.setColor('#333333');
      gridManager.setSpacing(50);
      gridManager.setOpacity(0.6);
    }
  }, []);
  
  return (
    <div ref={containerRef} style={{ width: '100%', height: '500px' }} />
  );
}

Advanced Usage

For more advanced usage examples and detailed API documentation, please refer to the API Documentation.

Using the Layer Manager

import React, { useEffect, useRef } from 'react';
import { CoordinatePlane, LayerManager, ImageLayer, Marker } from 'fabric-layers-react';

function AdvancedLayerManagement() {
  const containerRef = useRef(null);
  
  useEffect(() => {
    if (containerRef.current) {
      // Create coordinate plane
      const plane = new CoordinatePlane(containerRef.current);
      
      // Create a layer manager
      const layerManager = new LayerManager({
        coordinatePlane: plane
      });
      
      // Create layers
      const baseMap = new ImageLayer({
        id: 'base-map',
        url: 'path/to/map.png',
        position: { x: 0, y: 0 }
      });
      
      const marker1 = new Marker({
        id: 'marker-1',
        position: { x: 100, y: 100 },
        label: 'Location A'
      });
      
      const marker2 = new Marker({
        id: 'marker-2',
        position: { x: 200, y: 150 },
        label: 'Location B'
      });
      
      // Add layers to the manager
      layerManager.addLayer(baseMap);
      layerManager.addLayer(marker1);
      layerManager.addLayer(marker2);
      
      // Sort layers by z-index
      layerManager.sortLayers();
      
      // You can now easily manage layers
      // For example, to get a layer by id:
      const locationA = layerManager.getLayer('marker-1');
      
      // To hide all layers except the base map:
      layerManager.hideAllLayers();
      layerManager.getLayer('base-map').setVisible(true);
    }
  }, []);
  
  return (
    <div ref={containerRef} style={{ width: '100%', height: '500px' }} />
  );
}

Browser Support

fabric-layers-react works in all modern browsers that support Canvas, including:

• Chrome
• Firefox
• Safari
• Edge

Development

Building from Source

# Clone the repository
git clone https://github.com/ajoslin103/fabric-layers-react.git
cd fabric-layers-react

# Install dependencies
npm install

# Build the library
npm run build

# Run development server
npm start

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.