use-clipboard-history

A React hook for managing clipboard history with customizable UI components. Perfect for note apps, editors, admin dashboards, and anywhere users frequently copy and paste content.

Features

• 📋 Clipboard History Management - Track and manage copied content
• 🎨 Customizable UI Components - Pre-built components with modern styling
• 💾 Persistent Storage - Optional localStorage persistence
• 🔍 Search Functionality - Built-in search through clipboard history
• 📱 Responsive Design - Works on desktop and mobile
• 🔧 TypeScript Support - Full TypeScript definitions included
• 🚀 Lightweight - No heavy dependencies, just React

Installation

npm install use-clipboard-history
# or
yarn add use-clipboard-history

Quick Start

Basic Usage

import React from 'react';
import { useClipboardHistory } from 'use-clipboard-history';

function MyComponent() {
  const { history, copyToClipboard, addToHistory } = useClipboardHistory();

  const handleCopy = async (text: string) => {
    await copyToClipboard(text);
    // Content is automatically added to history
  };

  return (
    <div>
      <button onClick={() => handleCopy('Hello World!')}>
        Copy Text
      </button>
      
      <div>
        <h3>Clipboard History:</h3>
        {history.map(item => (
          <div key={item.id}>
            {item.content} - {new Date(item.timestamp).toLocaleString()}
          </div>
        ))}
      </div>
    </div>
  );
}

With Context Provider

import React from 'react';
import { 
  ClipboardHistoryProvider, 
  ClipboardHistoryWidget 
} from 'use-clipboard-history';

function App() {
  return (
    <ClipboardHistoryProvider 
      options={{
        maxItems: 100,
        persistToStorage: true,
        storageKey: 'my-app-clipboard',
      }}
    >
      <div>
        <h1>My App</h1>
        <ClipboardHistoryWidget />
      </div>
    </ClipboardHistoryProvider>
  );
}

API Reference

useClipboardHistory Hook

const {
  history,
  addToHistory,
  removeFromHistory,
  clearHistory,
  copyToClipboard,
  copyFromHistory,
  isSupported
} = useClipboardHistory(options);

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxItems | number | 50 | Maximum number of items to keep in history | | persistToStorage | boolean | false | Whether to persist history to localStorage | | storageKey | string | 'use-clipboard-history' | Key for localStorage | | includeImages | boolean | false | Whether to include images in history | | includeFiles | boolean | false | Whether to include files in history | | autoCopy | boolean | false | Automatically track clipboard changes |

Return Values

| Property | Type | Description | |----------|------|-------------| | history | ClipboardItem[] | Array of clipboard items | | addToHistory | (content: string, type?: string, metadata?: object) => void | Add item to history | | removeFromHistory | (id: string) => void | Remove item from history | | clearHistory | () => void | Clear all history | | copyToClipboard | (content: string) => Promise<void> | Copy content and add to history | | copyFromHistory | (id: string) => Promise<void> | Copy item from history | | isSupported | boolean | Whether clipboard API is supported |

ClipboardHistoryProvider

Context provider for sharing clipboard history across components.

<ClipboardHistoryProvider options={options}>
  {children}
</ClipboardHistoryProvider>

ClipboardHistoryWidget

A complete UI component with search, clear functionality, and modern styling.

<ClipboardHistoryWidget
  maxHeight="400px"
  showSearch={true}
  showClearButton={true}
  showStats={true}
  placeholder="Search clipboard history..."
  emptyMessage="No clipboard history yet"
  maxContentLength={100}
/>

ClipboardHistoryList

A simpler list component for custom implementations.

<ClipboardHistoryList
  maxHeight="300px"
  showTimestamps={true}
  showRemoveButton={true}
  onItemClick={(id, content) => console.log('Clicked:', content)}
  emptyMessage="No items"
  maxContentLength={80}
/>

Advanced Examples

Custom UI Implementation

import React from 'react';
import { useClipboardHistoryContext } from 'use-clipboard-history';

function CustomClipboardUI() {
  const { history, copyFromHistory, removeFromHistory } = useClipboardHistoryContext();

  return (
    <div className="custom-clipboard-ui">
      {history.map(item => (
        <div key={item.id} className="clipboard-item">
          <span>{item.content}</span>
          <button onClick={() => copyFromHistory(item.id)}>
            Copy
          </button>
          <button onClick={() => removeFromHistory(item.id)}>
            Remove
          </button>
        </div>
      ))}
    </div>
  );
}

Note Taking App Example

import React, { useState } from 'react';
import { 
  ClipboardHistoryProvider, 
  ClipboardHistoryWidget,
  useClipboardHistoryContext 
} from 'use-clipboard-history';

function NoteEditor() {
  const [notes, setNotes] = useState<string[]>([]);
  const { addToHistory } = useClipboardHistoryContext();

  const addNote = (content: string) => {
    setNotes(prev => [...prev, content]);
    addToHistory(content, 'text', { source: 'note-editor' });
  };

  return (
    <div style={{ display: 'flex', gap: '20px' }}>
      <div style={{ flex: 1 }}>
        <textarea 
          placeholder="Write your notes..."
          onChange={(e) => addNote(e.target.value)}
        />
      </div>
      <div style={{ width: '300px' }}>
        <ClipboardHistoryWidget />
      </div>
    </div>
  );
}

function NoteApp() {
  return (
    <ClipboardHistoryProvider options={{ persistToStorage: true }}>
      <NoteEditor />
    </ClipboardHistoryProvider>
  );
}

Admin Dashboard Example

import React from 'react';
import { 
  ClipboardHistoryProvider, 
  ClipboardHistoryWidget 
} from 'use-clipboard-history';

function AdminDashboard() {
  return (
    <div className="admin-dashboard">
      <header>
        <h1>Admin Dashboard</h1>
      </header>
      
      <div className="dashboard-content">
        <div className="sidebar">
          <ClipboardHistoryWidget 
            maxHeight="600px"
            showSearch={true}
            showStats={true}
            placeholder="Search copied content..."
          />
        </div>
        
        <div className="main-content">
          {/* Your dashboard content */}
        </div>
      </div>
    </div>
  );
}

function App() {
  return (
    <ClipboardHistoryProvider 
      options={{
        maxItems: 200,
        persistToStorage: true,
        storageKey: 'admin-clipboard-history',
      }}
    >
      <AdminDashboard />
    </ClipboardHistoryProvider>
  );
}

Browser Support

This package uses the modern Clipboard API with fallbacks for older browsers:

• ✅ Chrome 66+
• ✅ Firefox 63+
• ✅ Safari 13.1+
• ✅ Edge 79+

For older browsers, the package falls back to the document.execCommand('copy') method.

Contributing

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

License

MIT License - see the LICENSE file for details.