From Photo Roll - iOS

import IMGLYEditor
import SwiftUI

/// This example demonstrates how to integrate photo library access in CE.SDK iOS.
///
/// This example shows how to:
/// - Use the default photos picker mode (privacy-friendly, no permissions)
/// - Enable full photo library access mode
/// - Configure Info.plist for photo library permissions
struct PhotoRollSolution: View {
  let settings = EngineSettings(
    license: secrets.licenseKey,
    userID: "<your unique user id>",
  )

  // Default Photos Picker Mode
  // The photo roll button opens the system photos picker
  // No permissions required, maximum privacy
  var editorWithPhotosPicker: some View {
    Editor(settings)
      .imgly.configuration { DesignEditorConfiguration() }
    // PhotoRollAssetSource is automatically registered in default mode
    // Dock includes Dock.Buttons.photoRoll() by default
    // Users tap Photo Roll → System picker opens → Select photos
  }


  // Full Library Access Mode
  // Photo library is loaded directly into the CE.SDK Asset Panel
  // Requires photo library permissions on first use
  var editorWithFullLibrary: some View {
    Editor(settings)
      .imgly.configuration {
        DesignEditorConfiguration { builder in
          builder.onCreate { engine, _ in
            // Load or create scene
            let sceneURL = Bundle.main.url(forResource: "design-ui-empty", withExtension: "scene")!
            try await engine.scene.load(from: sceneURL) // or `engine.scene.create*`
            // Add asset sources
            try await engine.addDefaultAssetSources()
            try await engine.addDemoAssetSources(withUploadAssetSources: true)
            try await engine.asset.addSource(TextAssetSource(engine: engine))
            try engine.asset.addSource(PhotoRollAssetSource(engine: engine, mode: .fullLibraryAccess))
          }
        }
      }
    // IMPORTANT: Add NSPhotoLibraryUsageDescription to Info.plist
    // <key>NSPhotoLibraryUsageDescription</key>
    // <string>We need access to your photo library to let you add photos to your designs.</string>
  }


  @State private var isPresented = false
  @State private var useFullLibrary = false

  var body: some View {
    VStack {
      Toggle("Enable Full Library Access", isOn: $useFullLibrary)
        .padding()

      Button("Use the Editor") {
        isPresented = true
      }
    }
    .fullScreenCover(isPresented: $isPresented) {
      ModalEditor {
        if useFullLibrary {
          editorWithFullLibrary
        } else {
          editorWithPhotosPicker
        }
      }
    }
  }
}

#Preview {
  PhotoRollSolution()
}

Enable photo library access through two distinct modes: privacy-friendly photos picker (default) or full library integration with in-app browsing.

We integrate photo library access to let users add their personal photos and videos to designs. CE.SDK iOS provides two approaches: the system photos picker for maximum privacy, or full library access for rich browsing within the app.

Photo Roll asset source in CE.SDK iOS editor

Explore the complete code sample on GitHub.

Understanding Photo Roll Integration#

Photo Roll integration connects the iOS photo library to CE.SDK’s asset system. We choose between two modes based on privacy requirements and user experience needs.

Architecture:

The photo roll system consists of:

PhotoRollAssetSource - Asset source implementation for photo library
PhotoRollAssetSourceMode - Enum defining access mode (photosPicker or fullLibraryAccess)
Asset Panel Integration - Built-in UI for browsing and selecting photos
System Picker Integration - iOS photos picker for privacy-first access

Key Distinction:

Mode	User Experience	Permissions	Privacy Level
Photos Picker (default)	System picker UI	None required	Maximum - user controls selection
Full Library Access	In-app browsing	Photo library access	Standard - app can access full library

Default Behavior:

PhotoRollAssetSource is automatically registered in photos picker mode
Dock includes Dock.Buttons.photoRoll() by default
No permissions requested unless full library access is enabled
Works immediately without configuration

Photos Picker Mode (Default)#

We use photos picker mode when privacy is a priority and users need to select individual photos. The system picker handles selection without requiring photo library permissions.

How it works:

User taps Photo Roll button in dock
System photos picker opens (iOS native UI)
User selects individual photos
Selected photos become available in the asset source
No permission prompt - maximum privacy

// Default Photos Picker Mode
// The photo roll button opens the system photos picker
// No permissions required, maximum privacy
var editorWithPhotosPicker: some View {
  Editor(settings)
    .imgly.configuration { DesignEditorConfiguration() }
  // PhotoRollAssetSource is automatically registered in default mode
  // Dock includes Dock.Buttons.photoRoll() by default
  // Users tap Photo Roll → System picker opens → Select photos
}

Key Points:

No permissions required - System picker handles access
Maximum privacy - User controls exactly which photos app can access
iOS native UI - Familiar interface for users
Automatic setup - Works without configuration

Full Library Access Mode#

We use full library access mode when users need to browse their entire photo library within the app interface. This requires photo library permissions.

How it works:

User taps Photo Roll button in dock
Photo library loads directly into CE.SDK Asset Panel
Permission prompt appears on first use
User can browse entire library
Selected photos are added to the design

// Full Library Access Mode
// Photo library is loaded directly into the CE.SDK Asset Panel
// Requires photo library permissions on first use
var editorWithFullLibrary: some View {
  Editor(settings)
    .imgly.configuration {
      DesignEditorConfiguration { builder in
        builder.onCreate { engine, _ in
          // Load or create scene
          let sceneURL = Bundle.main.url(forResource: "design-ui-empty", withExtension: "scene")!
          try await engine.scene.load(from: sceneURL) // or `engine.scene.create*`
          // Add asset sources
          try await engine.addDefaultAssetSources()
          try await engine.addDemoAssetSources(withUploadAssetSources: true)
          try await engine.asset.addSource(TextAssetSource(engine: engine))
          try engine.asset.addSource(PhotoRollAssetSource(engine: engine, mode: .fullLibraryAccess))
        }
      }
    }
  // IMPORTANT: Add NSPhotoLibraryUsageDescription to Info.plist
  // <key>NSPhotoLibraryUsageDescription</key>
  // <string>We need access to your photo library to let you add photos to your designs.</string>
}

Important: When using builder.onCreate, you override the default behavior. Load the scene, add asset sources manually, and specify .fullLibraryAccess mode for PhotoRollAssetSource.

Permission Configuration:

Add NSPhotoLibraryUsageDescription to your Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your photo library to let you add photos to your designs.</string>

Key Points:

Requires permissions - Photo library access permission on first use
Rich browsing - Browse photos in-app
CE.SDK integration - Full asset library features available
Info.plist required - Must declare usage description
Custom onCreate - Load scene and asset sources manually with fullLibraryAccess mode

Common Use Cases#

Privacy-First Applications#

Use the default photos picker mode when privacy is paramount:

Editor(settings)
    .imgly.configuration { DesignEditorConfiguration() }
// Photo Roll automatically registered in photos picker mode
// No permissions required, maximum user privacy

When to use: Social media apps, messaging apps, any privacy-sensitive application.

Rich Browsing Experience#

Enable full library access when users need comprehensive photo management. See the complete code example above in the “Full Library Access Mode” section for the proper onCreate implementation.

When to use: Professional photo editing apps, design tools, content creation platforms.

Conditional Mode Selection#

Offer users the choice between privacy mode and full library access:

@State private var useFullLibrary = false

var body: some View {
  VStack {
    Toggle("Enable Full Library Access", isOn: $useFullLibrary)
    Button("Use the Editor") {
      // Present editor with selected mode
    }
  }
  .fullScreenCover(isPresented: $isPresented) {
    ModalEditor {
      if useFullLibrary {
        // Use full library mode (see Full Library Access Mode section)
      } else {
        // Use default photos picker mode
        Editor(settings)
          .imgly.configuration { DesignEditorConfiguration() }
      }
    }
  }
}

When to use: Apps that want to offer both privacy and power user features.

Troubleshooting#

Photo Roll Button Doesn’t Appear#

Symptom: Photo Roll button is missing from the dock

Causes:

Custom dock configuration removed default buttons
Dock items were replaced instead of modified

Solutions:

// ✅ Correct - Modify dock items, keep defaults
builder.dock { dock in
  dock.modify { _, items in
    // Add custom buttons
    items.addLast { /* custom button */ }
  }
}

// ❌ Wrong - Replaces all dock items
builder.dock { dock in
  dock.items { _ in
    // This removes default Photo Roll button
    Dock.Button(/* only custom button */)
  }
}

// ✅ Correct - Explicitly add photo roll button
builder.dock { dock in
  dock.modify { _, items in
    items.addFirst {
      Dock.Buttons.photoRoll()
    }
  }
}

Want Full Library Instead of Picker#

Symptom: System picker opens, but you want in-app browsing

Cause: Default mode is photos picker

Solution: Implement full library access mode using builder.onCreate. See the “Full Library Access Mode” section above for the complete implementation.

Don’t forget to add NSPhotoLibraryUsageDescription to Info.plist.

Permission Prompt Not Appearing#

Symptom: Full library mode enabled but no permission prompt

Causes:

NSPhotoLibraryUsageDescription missing from Info.plist
Permission already denied in Settings
Using photos picker mode instead of full library

Solutions:

// ✅ Verify mode is set correctly
PhotoRollAssetSource(engine: engine, mode: .fullLibraryAccess)

// ✅ Check Info.plist has required key
// Open Info.plist and verify NSPhotoLibraryUsageDescription exists

// ✅ Reset permissions (Settings → Privacy → Photos → Your App)

Next Steps#

Explore related UI customization guides:

Hide UI Elements - Control which editor components are visible