├─ Lives on disk (large files, videos, documents)?
│ → FileRepresentation (passes file URLs, not bytes)
├─ Need a fallback for receivers that don't understand your type?
│ → Add ProxyRepresentation (e.g., export as String or URL)
└─ Need to conditionally hide a representation?
→ Apply .exportingCondition to any representation
Common Errors
Error / Symptom
Cause
Fix
"Type does not conform to Transferable"
Missing
transferRepresentation
Add
static var transferRepresentation: some TransferRepresentation
Drop works in-app but not across apps
Custom UTType not declared in Info.plist
Add
UTExportedTypeDeclarations
entry
Receiver always gets plain text instead of rich type
ProxyRepresentation listed before CodableRepresentation
Reorder: richest representation first
FileRepresentation crashes with "file not found"
Receiver didn't copy file before sandbox extension expired
Copy to app storage in the importing closure
PasteButton always disabled
Pasteboard doesn't contain matching Transferable type
Check UTType conformance; verify the pasted data matches
ShareLink shows generic preview
No
SharePreview
provided or image isn't
Transferable
Supply explicit
SharePreview
with title and image
.dropDestination
closure never fires
Wrong payload type or view has zero hit-test area
Verify
for:
type matches dragged content; add
.frame()
or
.contentShape()
Built-in Transferable Types
These work with zero additional code — no conformance needed:
String
,
Data
,
URL
,
AttributedString
,
Image
,
Color
Part 2: Making Types Transferable
The
Transferable
protocol has one requirement: a static
transferRepresentation
property.
CodableRepresentation
Best for: models already conforming to
Codable
. Uses JSON by default.
import
UniformTypeIdentifiers
extension
UTType
{
static
var
todo
:
UTType
=
UTType
(
exportedAs
:
"com.example.todo"
)
}
struct
Todo
:
Codable
,
Transferable
{
var
text
:
String
var
isDone
:
Bool
static
var
transferRepresentation
:
some
TransferRepresentation
{
CodableRepresentation
(
contentType
:
.
todo
)
}
}
Custom encoder/decoder (e.g., PropertyList instead of JSON):
CodableRepresentation
(
contentType
:
.
todo
,
encoder
:
PropertyListEncoder
(
)
,
decoder
:
PropertyListDecoder
(
)
)
Requirement
Custom UTTypes need matching
UTExportedTypeDeclarations
in Info.plist (see Part 4).
DataRepresentation
Best for: custom binary formats where data is in memory and you control serialization.
struct
ProfilesArchive
:
Transferable
{
var
profiles
:
[
Profile
]
static
var
transferRepresentation
:
some
TransferRepresentation
{
DataRepresentation
(
contentType
:
.
commaSeparatedText
)
{
archive
in
try
archive
.
toCSV
(
)
}
importing
:
{
data
in
try
ProfilesArchive
(
csvData
:
data
)
}
}
}
Import-only or export-only variants:
// Import only
DataRepresentation
(
importedContentType
:
.
png
)
{
data
in
try
MyImage
(
pngData
:
data
)
}
// Export only
DataRepresentation
(
exportedContentType
:
.
png
)
{
image
in
try
image
.
pngData
(
)
}
Avoid
using
UTType.data
as the content type — use a specific type like
.png
,
.pdf
,
.commaSeparatedText
.
FileRepresentation
Best for: large payloads on disk (videos, documents, archives). Passes file URLs instead of loading bytes into memory.
struct
Video
:
Transferable
{
let
file
:
URL
static
var
transferRepresentation
:
some
TransferRepresentation
{
FileRepresentation
(
contentType
:
.
mpeg4Movie
)
{
video
in
SentTransferredFile
(
video
.
file
)
}
importing
:
{
received
in
// MUST copy — sandbox extension is temporary
let
dest
=
FileManager
.
default
.
temporaryDirectory
.
appendingPathComponent
(
UUID
(
)
.
uuidString
)
.
appendingPathExtension
(
"mp4"
)
try
FileManager
.
default
.
copyItem
(
at
:
received
.
file
,
to
:
dest
)
return
Video
(
file
:
dest
)
}
}
}
Critical
The
received.file
URL has a temporary sandbox extension. Copy the file to your own storage in the importing closure — the URL becomes inaccessible after the closure returns.
SentTransferredFile
properties:
file: URL
— the file location
allowAccessingOriginalFile: Bool
— when
false
(default), receiver gets a copy
ReceivedTransferredFile
properties:
file: URL
— the received file on disk
isOriginalFile: Bool
— whether this is the sender's original file or a copy
Content type precision
:
.mpeg4Movie
only matches
.mp4
files. To accept all common video formats (
.mp4
,
.mov
,
.m4v
), use the parent type
.movie
— or declare multiple
FileRepresentation
s for specific subtypes:
// Broad: accept any video format the system recognizes
FileRepresentation
(
contentType
:
.
movie
)
{
...
}
importing
:
{
...
}
// Or specific: separate handlers per format
FileRepresentation
(
contentType
:
.
mpeg4Movie
)
{
...
}
importing
:
{
...
}
FileRepresentation
(
contentType
:
.
quickTimeMovie
)
{
...
}
importing
:
{
...
}
Import-only
When your type only receives files (drop target, no export), use the import-only initializer — it makes intent explicit and avoids accidental export:
FileRepresentation
(
importedContentType
:
.
movie
)
{
received
in
let
dest
=
appStorageURL
.
appendingPathComponent
(
received
.
file
.
lastPathComponent
)
try
FileManager
.
default
.
copyItem
(
at
:
received
.
file
,
to
:
dest
)
return
VideoClip
(
localURL
:
dest
)
}
ProxyRepresentation
Best for: fallback representations that let your type work with receivers expecting simpler types.
struct
Profile
:
Transferable
{
var
name
:
String
var
avatar
:
Image
static
var
transferRepresentation
:
some
TransferRepresentation
{
CodableRepresentation
(
contentType
:
.
profile
)
ProxyRepresentation
(
exporting
:
\
.
name
)
// Fallback: paste as text
}
}
Export-only proxy (common pattern — reverse conversion often impossible):
ProxyRepresentation
(
exporting
:
\
.
name
)
// Profile → String (one-way)
Bidirectional proxy (when reverse makes sense):
ProxyRepresentation
{
item
in
item
.
name
// export
}
importing
:
{
name
in
Profile
(
name
:
name
)
// import
}
Combining Multiple Representations
List representations in the
transferRepresentation
body.
Order matters
— receivers use the first representation they support.
struct
Profile
:
Transferable
{
static
var
transferRepresentation
:
some
TransferRepresentation
{
// 1. Richest: full profile data (apps that understand .profile)
CodableRepresentation
(
contentType
:
.
profile
)
// 2. Fallback: plain text (text fields, notes, any app)
ProxyRepresentation
(
exporting
:
\
.
name
)
}
}
Common mistake
putting
ProxyRepresentation
first causes receivers that support both to always get the degraded version.
Conditional Export
Hide a representation at runtime when conditions aren't met:
DataRepresentation
(
contentType
:
.
commaSeparatedText
)
{
archive
in
try
archive
.
toCSV
(
)
}
importing
:
{
data
in
try
Self
(
csvData
:
data
)
}
.
exportingCondition
{
archive
in
archive
.
supportsCSV
}
Visibility
Control which processes can see a representation:
CodableRepresentation
(
contentType
:
.
profile
)
.
visibility
(
.
ownProcess
)
// Only within this app
Options:
.all
(default),
.team
(same developer team),
.group
(same App Group, macOS),
.ownProcess
(same app only)
Suggested File Name
Hint for receivers writing to disk:
FileRepresentation
(
contentType
:
.
mpeg4Movie
)
{
video
in
SentTransferredFile
(
video
.
file
)
}
importing
:
{
received
in
// ...
}
.
suggestedFileName
(
"My Video.mp4"
)
// Or dynamic:
.
suggestedFileName
{
video
in
video
.
title
+
".mp4"
}
Part 3: SwiftUI Surfaces
ShareLink
The standard sharing entry point. Accepts any
Transferable
type.
// Simple: share a string
ShareLink
(
item
:
"Check out this app!"
)
// With preview
ShareLink
(
item
:
photo
,
preview
:
SharePreview
(
photo
.
caption
,
image
:
photo
.
image
)
)
// Share a URL with custom preview (prevents system metadata fetch)
for a custom type, the share sheet shows a generic preview. Always provide one for non-trivial types.
Drag and Drop
Making a view draggable:
Text
(
profile
.
name
)
.
draggable
(
profile
)
With custom drag preview:
Text
(
profile
.
name
)
.
draggable
(
profile
)
{
Label
(
profile
.
name
,
systemImage
:
"person"
)
.
padding
(
)
.
background
(
.
regularMaterial
)
}
Accepting drops:
Color
.
clear
.
frame
(
width
:
200
,
height
:
200
)
.
dropDestination
(
for
:
Profile
.
self
)
{
profiles
,
location
in
guard
let
profile
=
profiles
.
first
else
{
return
false
}
self
.
droppedProfile
=
profile
return
true
}
isTargeted
:
{
isTargeted
in
self
.
isDropTargeted
=
isTargeted
}
Multiple item types
— use an enum wrapper conforming to
Transferable
rather than stacking
.dropDestination
modifiers (stacking may cause only the outermost handler to fire):
enum
DroppableItem
:
Transferable
{
case
image
(
Image
)
case
text
(
String
)
static
var
transferRepresentation
:
some
TransferRepresentation
{
ProxyRepresentation
{
(
image
:
Image
)
in
DroppableItem
.
image
(
image
)
}
ProxyRepresentation
{
(
text
:
String
)
in
DroppableItem
.
text
(
text
)
}
}
}
myView
.
dropDestination
(
for
:
DroppableItem
.
self
)
{
items
,
_
in
for
item
in
items
{
switch
item
{
case
.
image
(
let
img
)
:
handleImage
(
img
)
case
.
text
(
let
str
)
:
handleString
(
str
)
}
}
return
true
}
ForEach with reordering
— combine with
.onMove
or use
draggable
/
dropDestination
for cross-container moves.
Clipboard (Copy/Paste)
Copy support
(activates Edit > Copy / Cmd+C):
List
(
items
)
{
item
in
Text
(
item
.
name
)
}
.
copyable
(
items
)
Paste support
(activates Edit > Paste / Cmd+V):
List
(
items
)
{
item
in
Text
(
item
.
name
)
}
.
pasteDestination
(
for
:
Item
.
self
)
{
pasted
in
items
.
append
(
contentsOf
:
pasted
)
}
validator
:
{
candidates
in
candidates
.
filter
{
$0
.
isValid
}
}
The validator closure runs before the action — return an empty array to prevent the paste.
Cut support:
.
cuttable
(
for
:
Item
.
self
)
{
let
selected
=
items
.
filter
{
$0
.
isSelected
}
items
.
removeAll
{
$0
.
isSelected
}
return
selected
}
PasteButton
— system button that handles paste with type filtering:
PasteButton
(
payloadType
:
String
.
self
)
{
strings
in
notes
.
append
(
contentsOf
:
strings
)
}
Platform difference: PasteButton auto-validates pasteboard changes on iOS but not on macOS.
Availability
:
.copyable
,
.pasteDestination
, and
.cuttable
are
macOS 13+ only
— they do not exist on iOS. On iOS, use
PasteButton
(iOS 16+) for paste, and standard context menus or
UIPasteboard
for programmatic copy/cut.
PasteButton
is cross-platform: macOS 10.15+, iOS 16+, visionOS 1.0+.
Part 4: UTType Declarations
System Types
Use Apple's built-in UTTypes when possible — they're already recognized across the system:
import
UniformTypeIdentifiers
// Common types
UTType
.
plainText
// public.plain-text
UTType
.
utf8PlainText
// public.utf8-plain-text
UTType
.
json
// public.json
UTType
.
png
// public.png
UTType
.
jpeg
// public.jpeg
UTType
.
pdf
// com.adobe.pdf
UTType
.
mpeg4Movie
// public.mpeg-4
UTType
.
commaSeparatedText
// public.comma-separated-values-text
Declaring Custom Types
Step 1
Declare in Swift:
extension
UTType
{
static
var
recipe
:
UTType
=
UTType
(
exportedAs
:
"com.myapp.recipe"
)
}
Step 2
Add to Info.plist under
UTExportedTypeDeclarations
:
<
key
>
UTExportedTypeDeclarations
</
key
>
<
array
>
<
dict
>
<
key
>
UTTypeIdentifier
</
key
>
<
string
>
com.myapp.recipe
</
string
>
<
key
>
UTTypeDescription
</
key
>
<
string
>
Recipe
</
string
>
<
key
>
UTTypeConformsTo
</
key
>
<
array
>
<
string
>
public.data
</
string
>
</
array
>
<
key
>
UTTypeTagSpecification
</
key
>
<
dict
>
<
key
>
public.filename-extension
</
key
>
<
array
>
<
string
>
recipe
</
string
>
</
array
>
</
dict
>
</
dict
>
</
array
>
Both are required.
The Swift declaration alone makes it compile, but cross-app transfers silently fail without the Info.plist entry.
Imported vs Exported Types
Exported
(
exportedAs:
) — Your app owns this type. Use for app-specific formats.
Imported
(
importedAs:
) — Another app owns this type. Use when you want to accept their format.
UTType Conformance
Custom types should conform to system types for broader compatibility:
// Your .recipe conforms to public.data (binary data)
// This means any receiver that accepts generic data can also accept recipes
Common conformance parents:
public.data
,
public.content
,
public.text
,
public.image
Part 5: UIKit Bridging
NSItemProvider + Transferable
Bridge between UIKit's
NSItemProvider
(used by
UIActivityViewController
, extensions, drag sessions) and
Transferable
:
// Load a Transferable from an NSItemProvider
let
provider
:
NSItemProvider
=
// from drag session, extension, etc.
provider
.
loadTransferable
(
type
:
Profile
.
self
)
{
result
in
switch
result
{
case
.
success
(
let
profile
)
:
// Use the profile
case
.
failure
(
let
error
)
:
// Handle error
}
}
When to Use UIActivityViewController
ShareLink
covers most sharing needs. Use
UIActivityViewController
when you need:
Custom activity items or excluded activity types
UIActivityItemsConfiguration
for lazy item provision
Custom
UIActivity
subclasses
Programmatic presentation control
struct
ShareSheet
:
UIViewControllerRepresentable
{
let
items
:
[
Any
]
func
makeUIViewController
(
context
:
Context
)
->
UIActivityViewController
{
UIActivityViewController
(
activityItems
:
items
,
applicationActivities
:
nil
)
}
func
updateUIViewController
(
_
vc
:
UIActivityViewController
,
context
:
Context
)
{
}
}
For most apps,
ShareLink
is sufficient and preferred — it integrates with
Transferable
natively.
Part 6: Gotchas & Troubleshooting
FileRepresentation Temporary File Lifecycle
The
received.file
URL in a
FileRepresentation
importing closure has a temporary sandbox extension. The system may revoke access after the closure returns. Always copy the file:
// WRONG — file may become inaccessible
return
Video
(
file
:
received
.
file
)
// RIGHT — copy to your own storage
let
dest
=
myAppDirectory
.
appendingPathComponent
(
received
.
file
.
lastPathComponent
)
try
FileManager
.
default
.
copyItem
(
at
:
received
.
file
,
to
:
dest
)
return
Video
(
file
:
dest
)
Async Work After File Drop
The
FileRepresentation
importing closure is synchronous — you cannot
await
inside it. Copy the file first, return the model, then do async post-processing (thumbnails, transcoding, metadata extraction) on the copied URL:
// WRONG — can't await in the importing closure
FileRepresentation
(
importedContentType
:
.
movie
)
{
received
in
let
dest
=
...
try
FileManager
.
default
.
copyItem
(
at
:
received
.
file
,
to
:
dest
)
let
thumbnail
=
await
generateThumbnail
(
for
:
dest
)
// ❌ compile error
return
VideoClip
(
localURL
:
dest
,
thumbnail
:
thumbnail
)
}
// RIGHT — return immediately, process async afterward
// In your view model or drop handler:
.
dropDestination
(
for
:
VideoClip
.
self
)
{
clips
,
_
in
for
clip
in
clips
{
timeline
.
append
(
clip
)
Task
{
// clip.localURL is the COPY — safe to access anytime
let
thumbnail
=
await
generateThumbnail
(
for
:
clip
.
localURL
)
clip
.
thumbnail
=
thumbnail
}
}
return
true
}
Representation Ordering
Representations are tried
in declaration order
. The receiver uses the first one it supports.
// WRONG — receivers always get plain text
static
var
transferRepresentation
:
some
TransferRepresentation
{
ProxyRepresentation
(
exporting
:
\
.
name
)
// ← every receiver supports String
CodableRepresentation
(
contentType
:
.
profile
)
// ← never reached
}
// RIGHT — richest first, fallbacks last
static
var
transferRepresentation
:
some
TransferRepresentation
{
CodableRepresentation
(
contentType
:
.
profile
)
// ← apps that understand Profile
ProxyRepresentation
(
exporting
:
\
.
name
)
// ← fallback for everyone else
}
Custom UTType Without Info.plist
If you declare
UTType(exportedAs: "com.myapp.type")
in Swift but forget the Info.plist entry:
In-app transfers work (same process recognizes the type)
Cross-app transfers silently fail (other apps can't resolve the type)
This is the most common "works in development, fails in production" issue.
Drop Target Hit Testing
.dropDestination
requires the view to have a non-zero frame for hit testing. If drops aren't registering:
// WRONG — Color.clear has zero intrinsic size
Color
.
clear
.
dropDestination
(
for
:
Image
.
self
)
{
...
}
// RIGHT — give it a frame
Color
.
clear
.
frame
(
width
:
200
,
height
:
200
)
.
contentShape
(
Rectangle
(
)
)
// ensure full area is hit-testable
.
dropDestination
(
for
:
Image
.
self
)
{
...
}
Async Loading with loadTransferable
NSItemProvider.loadTransferable
is asynchronous. Update UI on the main actor:
provider
.
loadTransferable
(
type
:
Profile
.
self
)
{
result
in
Task
{
@MainActor
in
switch
result
{
case
.
success
(
let
profile
)
:
self
.
profile
=
profile
case
.
failure
(
let
error
)
:
self
.
errorMessage
=
error
.
localizedDescription
}
}
}
PasteButton Platform Differences
PasteButton
auto-validates against pasteboard changes on iOS — the button enables/disables as the pasteboard content changes. On macOS, this automatic validation does not occur. If your macOS app needs dynamic paste validation, monitor