0
# React Copy to Clipboard
1

2
React Copy to Clipboard is a React component library that provides a simple wrapper component for adding copy-to-clipboard functionality to any child element. It enables developers to easily add copy-to-clipboard features to their React applications by wrapping existing elements (buttons, spans, etc.) with the `CopyToClipboard` component.
3

4
## Package Information
5

6
- **Package Name**: react-copy-to-clipboard
7
- **Package Type**: npm
8
- **Language**: JavaScript (React)
9
- **Installation**: `npm install react-copy-to-clipboard`
10

11
## Core Imports
12

13
```javascript
14
import { CopyToClipboard } from "react-copy-to-clipboard";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { CopyToClipboard } = require("react-copy-to-clipboard");
21
```
22

23
Alternative default import:
24

25
```javascript
26
import CopyToClipboard from "react-copy-to-clipboard";
27
```
28

29
## Basic Usage
30

31
```javascript
32
import React from 'react';
33
import { CopyToClipboard } from 'react-copy-to-clipboard';
34

35
class App extends React.Component {
36
  state = {
37
    value: 'Hello World!',
38
    copied: false,
39
  };
40

41
  render() {
42
    return (
43
      <div>
44
        <input 
45
          value={this.state.value}
46
          onChange={({target: {value}}) => this.setState({value, copied: false})} 
47
        />
48

49
        <CopyToClipboard 
50
          text={this.state.value}
51
          onCopy={() => this.setState({copied: true})}>
52
          <button>Copy to clipboard</button>
53
        </CopyToClipboard>
54

55
        {this.state.copied ? <span style={{color: 'red'}}>Copied!</span> : null}
56
      </div>
57
    );
58
  }
59
}
60
```
61

62
## Capabilities
63

64
### CopyToClipboard Component
65

66
React component that wraps any child element to provide copy-to-clipboard functionality when clicked.
67

68
```javascript { .api }
69
/**
70
 * Copy-to-clipboard React component wrapper
71
 */
72
class CopyToClipboard extends React.PureComponent {
73
  static propTypes = {
74
    text: PropTypes.string.isRequired,
75
    children: PropTypes.element.isRequired,
76
    onCopy: PropTypes.func,
77
    options: PropTypes.shape({
78
      debug: PropTypes.bool,
79
      message: PropTypes.string,
80
      format: PropTypes.string
81
    })
82
  };
83
}
84
```
85

86
#### Required Props
87

88
**text**: `string` (required)
89
- Text content to be copied to clipboard
90
- The actual text that will be copied when the wrapped element is clicked
91

92
**children**: `React.Element` (required)
93
- Single child React element that will trigger copy action when clicked
94
- Must be exactly one React element (button, span, div, etc.)
95
- Cannot be multiple children or fragments
96

97
#### Optional Props
98

99
**onCopy**: `(text: string, result: boolean) => void` (optional)
100
- Callback function called after copy operation completes
101
- Parameters:
102
  - `text`: The text that was copied
103
  - `result`: `true` if copy was successful, `false` otherwise
104
- Called whether copy succeeds or fails
105

106
**options**: `object` (optional)
107
- Configuration object passed to underlying copy-to-clipboard library
108
- Properties:
109
  - `debug` (boolean): Enable debug mode for copy-to-clipboard
110
  - `message` (string): Custom message to show in fallback prompt
111
  - `format` (string): MIME type for clipboard format
112
- See [copy-to-clipboard API docs](https://npm.im/copy-to-clipboard#api) for complete options
113

114
#### Component Behavior
115

116
- **Event Handling**: Preserves existing `onClick` handlers on child elements - child's `onClick` will be called after the copy operation
117
- **Props Forwarding**: Forwards all additional props (className, style, etc.) to the child element
118
- **Render Method**: Clones the child element and adds the copy functionality via `onClick` handler
119
- **Copy Mechanism**: Uses the `copy-to-clipboard` library internally for cross-browser compatibility
120

121
**Usage Examples:**
122

123
```javascript
124
// Basic button wrapper
125
<CopyToClipboard text="Hello World!">
126
  <button>Copy to clipboard</button>
127
</CopyToClipboard>
128

129
// With callback handling
130
<CopyToClipboard 
131
  text="Hello World!"
132
  onCopy={(text, result) => {
133
    if (result) {
134
      console.log('Successfully copied:', text);
135
    } else {
136
      console.log('Copy failed');
137
    }
138
  }}>
139
  <button>Copy to clipboard</button>
140
</CopyToClipboard>
141

142
// With options and existing onClick
143
<CopyToClipboard
144
  text="Hello World!"
145
  options={{message: 'Press Ctrl+C to copy'}}
146
  onCopy={() => alert('Copied!')}>
147
  <button onClick={() => console.log('Button clicked!')}>
148
    Copy to clipboard
149
  </button>
150
</CopyToClipboard>
151

152
// Forwarding props to child
153
<CopyToClipboard text="Hello World!">
154
  <span className="copy-button" style={{cursor: 'pointer'}}>
155
    Click to copy
156
  </span>
157
</CopyToClipboard>
158
```
159

160
## Types
161

162
```javascript { .api }
163
// PropTypes definitions (JavaScript)
164
CopyToClipboard.propTypes = {
165
  text: PropTypes.string.isRequired,
166
  children: PropTypes.element.isRequired,
167
  onCopy: PropTypes.func,
168
  options: PropTypes.shape({
169
    debug: PropTypes.bool,
170
    message: PropTypes.string,
171
    format: PropTypes.string
172
  })
173
};
174

175
CopyToClipboard.defaultProps = {
176
  onCopy: undefined,
177
  options: undefined
178
};
179
```
180

181
## Platform Compatibility
182

183
- **React Versions**: ^15.3.0 || 16 || 17 || 18
184
- **Environment**: Browser environment (requires DOM for clipboard access)
185
- **Build Formats**: 
186
  - CommonJS: `lib/index.js`
187
  - UMD: `build/react-copy-to-clipboard.js` (global: `CopyToClipboard`)
188
- **Dependencies**: Requires `copy-to-clipboard` ^3.3.1 and `prop-types` ^15.8.1
189

190
## Error Handling
191

192
The component handles copy operation failures gracefully:
193
- If copy fails, `onCopy` callback receives `result: false`
194
- No exceptions are thrown on copy failure
195
- Fallback behavior is handled by the underlying `copy-to-clipboard` library