<!--
{
  "availability" : [
    "macOS: 10.6.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AppKit",
  "identifier" : "/documentation/AppKit/NSPasteboardItem",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AppKit"
    ],
    "preciseIdentifier" : "c:objc(cs)NSPasteboardItem"
  },
  "title" : "NSPasteboardItem"
}
-->

# NSPasteboardItem

An item on a pasteboard.

```
class NSPasteboardItem
```

## Overview

There are three main uses for an [`NSPasteboardItem`](/documentation/AppKit/NSPasteboardItem) object:

- Providing data on the pasteboard.

You can create one or more pasteboard items, set data or data providers for types, and write them to the pasteboard.

- Customizing data already on the pasteboard.

As a delegate or subclass, you can retrieve the pasteboard items currently on the pasteboard, read the existing types and data, and set new data and data providers for types as necessary.

- Retrieving data from the pasteboard.

You can retrieve pasteboard items from the pasteboard and then read the data for types you’re interested in.

A pasteboard item can be associated with a single pasteboard. When you create an item, you can write it to any pasteboard. When you pass an item to a pasteboard in [`writeObjects(_:)`](/documentation/AppKit/NSPasteboard/writeObjects(_:)), that item becomes bound to the pasteboard it writes to. When you retrieve items from a pasteboard using [`pasteboardItems`](/documentation/AppKit/NSPasteboard/pasteboardItems) or [`readObjects(forClasses:options:)`](/documentation/AppKit/NSPasteboard/readObjects(forClasses:options:)), the returned items are associated with the messaged pasteboard. Passing an item that is already associated with a pasteboard into [`writeObjects(_:)`](/documentation/AppKit/NSPasteboard/writeObjects(_:)) causes an exception.

Use pasteboard items during a single pasteboard interaction, rather than retaining and reusing them. A pasteboard item is only valid until the owner of the pasteboard changes.

> Important:
> When a pasteboard item’s owner changes, it becomes stale and its methods return an empty array, `nil`, or <doc://com.apple.documentation/documentation/Swift/false>.

## Topics

### Getting types

[`types`](/documentation/AppKit/NSPasteboardItem/types)

An array of uniform type identifier strings of the data types that the receiver supports.

[`availableType(from:)`](/documentation/AppKit/NSPasteboardItem/availableType(from:))

Returns from a given array of types the first type within the pasteboard item, according to the ordering of types.

### Setting the data provider

[`setDataProvider(_:forTypes:)`](/documentation/AppKit/NSPasteboardItem/setDataProvider(_:forTypes:))

Sets the data provider for the specified types.

### Setting values

[`setData(_:forType:)`](/documentation/AppKit/NSPasteboardItem/setData(_:forType:))

Sets the value for a specified type as a data object.

[`setString(_:forType:)`](/documentation/AppKit/NSPasteboardItem/setString(_:forType:))

Sets the value for a specified type as a string.

[`setPropertyList(_:forType:)`](/documentation/AppKit/NSPasteboardItem/setPropertyList(_:forType:))

Sets the value for a specified type as a property list.

### Getting values

[`data(forType:)`](/documentation/AppKit/NSPasteboardItem/data(forType:))

Returns the value for the specified type as a data object.

[`string(forType:)`](/documentation/AppKit/NSPasteboardItem/string(forType:))

Returns the value for the specified type as a string.

[`propertyList(forType:)`](/documentation/AppKit/NSPasteboardItem/propertyList(forType:))

Returns the value for the specified type as a property list.

### Detecting patterns and metadata in pasteboard items

[`detectedPatterns(for:)`](/documentation/AppKit/NSPasteboardItem/detectedPatterns(for:))

Determines whether the pasteboard item matches the specified patterns, without notifying the person using the app.

[`detectPatternsForPatterns:completionHandler:`](/documentation/AppKit/NSPasteboardItem/detectPatternsForPatterns:completionHandler:)

Determines whether this pasteboard item matches the specified patterns, without notifying the person using the app.

[`detectedValues(for:)`](/documentation/AppKit/NSPasteboardItem/detectedValues(for:))

Determines whether this pasteboard item matches the specified patterns, reading the contents if it finds a match.

[`detectValuesForPatterns:completionHandler:`](/documentation/AppKit/NSPasteboardItem/detectValuesForPatterns:completionHandler:)

Determines whether this pasteboard item matches the specified patterns, reading the contents if it finds a match.

[`NSPasteboardItem.DetectedValues`](/documentation/AppKit/NSPasteboardItem/DetectedValues)

[`detectedMetadata(for:)`](/documentation/AppKit/NSPasteboardItem/detectedMetadata(for:))

Determines available metadata from the specified metadata types for this pasteboard item, without notifying the person using the app.

[`detectMetadataForTypes:completionHandler:`](/documentation/AppKit/NSPasteboardItem/detectMetadataForTypes:completionHandler:)

Determines available metadata from the specified metadata types for this pasteboard item, without notifying the person using the app.

[`NSPasteboardItem.DetectedMetadata`](/documentation/AppKit/NSPasteboardItem/DetectedMetadata)


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)