use-clipboard-history

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.