@creaditor/attached-files-plugin

v1.0.3

Published

2 months ago

A flexible and modern file attachment component built with Lit

0High
0Medium
0Low

creaditor

web-components lit file-upload attachments

Attached Files Plugin

A flexible and modern file attachment component built with Lit, featuring support for multiple file types, previews, and a user-friendly interface.

Features

📁 Support for multiple file types (images, PDFs, videos, audio)
🖼️ File previews for images
🗑️ Easy file removal
📏 Configurable maximum file limit
🔄 Loading states and animations
🌐 Built-in internationalization support
🎯 Accessible and semantic HTML structure

Installation

NPM

npm install @creaditor/attached-files-plugin

CDN

<!-- Load dependencies -->
<script type="module" src="https://unpkg.com/[email protected]/lit.js"></script>
<script type="module" src="https://unpkg.com/@lit-labs/[email protected]/signals.js"></script>
<script type="module" src="https://unpkg.com/@creaditor/button@latest/dist/button.umd.js"></script>
<script type="module" src="https://unpkg.com/@creaditor/popover@latest/dist/popover.umd.js"></script>
<script type="module" src="https://unpkg.com/@creaditor/grid@latest/dist/grid.umd.js"></script>

<!-- Load the component -->
<script type="module" src="https://unpkg.com/@creaditor/attached-files-plugin@latest/dist/attached-files-plugin.umd.js"></script>

Usage

NPM Usage

import '@creaditor/attached-files-plugin';

<!-- Basic usage -->
<cdtr-attached-files-plugin></cdtr-attached-files-plugin>

<!-- With custom properties -->
<cdtr-attached-files-plugin
  max-files="5"
  button-text="Upload Files"
  add-files-text="Click to add files"
  max-files-reached-text="You've reached the maximum number of files"
></cdtr-attached-files-plugin>

CDN Usage

<!DOCTYPE html>
<html>
  <head>
    <title>Attached Files Plugin Demo</title>
    <!-- Load dependencies -->
    <script type="module" src="https://unpkg.com/[email protected]/lit.js"></script>
    <script type="module" src="https://unpkg.com/@lit-labs/[email protected]/signals.js"></script>
    <script type="module" src="https://unpkg.com/@creaditor/button@latest/dist/button.umd.js"></script>
    <script type="module" src="https://unpkg.com/@creaditor/popover@latest/dist/popover.umd.js"></script>
    <script type="module" src="https://unpkg.com/@creaditor/grid@latest/dist/grid.umd.js"></script>
    <!-- Load the component -->
    <script type="module" src="https://unpkg.com/@creaditor/attached-files-plugin@latest/dist/attached-files-plugin.umd.js"></script>
  </head>
  <body>
    <cdtr-attached-files-plugin></cdtr-attached-files-plugin>
  </body>
</html>

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | files | Array | [] | Array of attached files | | maxFiles | Number | Infinity | Maximum number of files allowed | | isLoading | Boolean | false | Loading state indicator | | buttonText | String | "Attached Files" | Text for the main button | | addFilesText | String | "Add Files" | Text for the add files button | | maxFilesReachedText | String | "Maximum number of files reached" | Text shown when max files is reached |

Events

The component dispatches the following custom events:

file-added: Dispatched when a new file is added

element.addEventListener('file-added', (e) => {
  console.log('File added:', e.detail);
});

file-removed: Dispatched when a file is removed

element.addEventListener('file-removed', (e) => {
  console.log('File removed:', e.detail);
});

max-files-reached: Dispatched when trying to add more files than allowed

element.addEventListener('max-files-reached', (e) => {
  console.log('Max files reached:', e.detail.maxFiles);
});

File Structure

Each file in the files array has the following structure:

interface FileItem {
  id: string;      // Unique identifier
  name: string;    // File name
  type: string;    // File type (image, pdf, video, audio)
  url: string;     // File URL or data URL
  size?: number;   // File size in bytes (optional)
}

Styling

The component uses CSS custom properties and can be styled using standard CSS. Key features include:

Responsive grid layout
File preview cards
Loading animations
Hover effects
Proper spacing and typography

Browser Support

The component is built using modern web standards and works in all modern browsers that support:

Custom Elements
Shadow DOM
CSS Grid
CSS Flexbox

Dependencies

@creaditor/popover - For the popover functionality
@creaditor/button - For button components
@creaditor/grid - For grid layout
@lit-labs/signals - For reactive state management
Lit - For web component functionality

License

MIT