NgCropper

Modern Angular image cropper library built on CropperJS with enhanced configuration architecture and optional built-in toolbar.

🚀 Quick Links

• 📚 Documentation & API - Complete Storybook documentation
• 🎮 Live Playground - Interactive demo
• 📦 NPM Package - Install the library
• 📋 Changelog - Release notes and updates

✨ Features

• 🎯 Zero Dependencies - Built-in SVG icons, no external icon libraries required
• ⚡ Modern Angular - Supports Angular 17.1+ with latest features
• 🎨 Highly Customizable - Comprehensive configuration objects for every component
• 🛠️ Built-in Toolbar - Optional toolbar with customizable icons and actions
• 📱 Responsive - Works seamlessly across all devices
• 💪 TypeScript Ready - Full type definitions and strict typing
• 🎛️ Flexible API - Both individual properties and config objects supported

📦 Installation

npm install ng-cropper-lib
# or
pnpm add ng-cropper-lib
# or
yarn add ng-cropper-lib

🚀 Quick Start

import { Component } from '@angular/core';
import { NgCropper } from 'ng-cropper-lib';

@Component({
  selector: 'app-demo',
  imports: [NgCropper],
  template: `
    <ngCropper
      [imageSrc]="'https://picsum.photos/800/600'"
      [showToolbar]="true"
      toolbarPosition="bottom"
      [selectionInitialCoverage]="0.6"
    />
  `
})
export class DemoComponent {}

🏗️ Project Structure

This monorepo contains multiple packages and applications:

ng-cropper/
├── libs/ng-cropper/              # 📦 Main library package
│   ├── src/lib/                  # Library source code
│   ├── README.md                 # Library documentation
│   └── package.json              # NPM package configuration
├── apps/ng-cropper-playground/   # 🎮 Demo application
├── .github/workflows/            # 🚀 CI/CD automation
│   ├── deploy.yml                # Deploy docs & demo
│   └── publish.yml               # Publish to NPM
├── CHANGELOG.md                  # 📋 Release notes
└── README.md                     # This file

📦 Library (libs/ng-cropper/)

The main Angular library package published to NPM as ng-cropper-lib.

• Source: libs/ng-cropper/src/lib/
• Documentation: Storybook
• Package: ng-cropper-lib

🎮 Demo Application (apps/ng-cropper-playground/)

Interactive demo application showcasing the library features.

• Live Demo: ng-cropper-playground
• Source: apps/ng-cropper-playground/src/

🛠️ Development

This project uses Nx for workspace management.

Prerequisites

• Node.js 18+
• pnpm (recommended)

Setup

# Clone the repository
git clone https://github.com/DanielGabbay/ng-cropper.git
cd ng-cropper

# Install dependencies
pnpm install

Development Commands

# Start development playground
pnpm dev

# Start Storybook documentation
pnpm storybook

# Build library
pnpm build:lib

# Run tests
pnpm test:lib

# Lint code
pnpm lint

🚀 Deployment

Automated CI/CD

This project uses GitHub Actions for automated deployment:

• 📚 Documentation & Demo: Auto-deployed to GitHub Pages on every push to master
• 📦 NPM Publishing: Auto-published when creating a GitHub release

Manual Publishing

# Build the library
pnpm build:lib

# Publish to NPM
cd dist/libs/ng-cropper
npm publish

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

☕ Support the Project

If NgCropper has been helpful to you, consider supporting its development:

Your support helps maintain and improve this project!

🙏 Acknowledgments

• Built on top of CropperJS by Fengyuan Chen
• Powered by Angular and Nx

---

⭐ Star this project if you find it useful!