T-Shirt Designer: iOS starter kit - iOS

import IMGLYEditor
import IMGLYEngine
import SwiftUI

// MARK: - Starter Kit View

struct ApparelEditorStarterKit: View {
  // Provide `EngineSettings` with your license and an optional userId.
  let settings = EngineSettings(
    license: secrets.licenseKey, // Use nil for evaluation mode with watermark
    userID: "<your unique user id>",
  )

  var body: some View {
    Editor(settings)
      .imgly.configuration {
        ApparelEditorConfiguration()
      }
  }
}

// MARK: - Preview

#Preview {
  ApparelEditorStarterKit()
}

import CoreGraphics
import Foundation
import IMGLYEditor
import IMGLYEngine

// MARK: - Default OnCreate

public extension ApparelEditorConfiguration {
  /// The default `onCreate` handler.
  internal static var defaultOnCreateHandler: OnCreate.Handler {
    { engine, _ in
      try await defaultOnCreate()(engine)
    }
  }

  /// Default apparel editor specific `OnCreate.Callback` implementation with solution specific settings, scene
  /// and editor creation setup.
  /// - Parameters:
  ///   - preCreateScene: Callback to do any pre scene loading tasks such as applying settings.
  ///   Defaults to `ApparelEditorConfiguration.defaultPreCreateScene`.
  ///   - createScene: Callback to load/create the scene and load asset sources. Defaults to
  /// `ApparelEditorConfiguration.defaultCreateScene`.
  ///   - loadAssetSources: Callback to load any asset sources. Defaults to
  /// `ApparelEditorConfiguration.defaultLoadAssetSources`.
  ///   - postCreateScene: Callback to do any post scene loading tasks. Defaults to
  ///   `ApparelEditorConfiguration.defaultPostCreateScene`.
  /// - Returns: A composed `OnCreate.Callback`that sequentially executes all three initialization phases.
  static func defaultOnCreate(
    preCreateScene: @escaping OnCreate.Callback = defaultPreCreateScene,
    createScene: @escaping OnCreate.Callback = defaultCreateScene,
    loadAssetSources: @escaping OnCreate.Callback = defaultLoadAssetSources,
    postCreateScene: @escaping OnCreate.Callback = defaultPostCreateScene,
  ) -> OnCreate.Callback {
    { engine in
      try await preCreateScene(engine)
      try await createScene(engine)
      try await loadAssetSources(engine)
      try await postCreateScene(engine)
    }
  }

  /// Configures engine settings before scene loading.
  ///
  /// Sets editor role, touch gestures, camera clamping, and global scopes.
  static let defaultPreCreateScene: OnCreate.Callback = { engine in
    try engine.editor.setRole("Adopter")
    try engine.editor.setSettingEnum("camera/clamping/overshootMode", value: "Center")

    let highlightColor: IMGLYEngine.Color = try engine.editor.getSettingColor("highlightColor")
    try engine.editor.setSettingColor("placeholderHighlightColor", color: highlightColor)

    try engine.editor.setSettingBool("touch/dragStartCanSelect", value: false)
    try engine.editor.setSettingEnum("touch/pinchAction", value: "Zoom")
    try engine.editor.setSettingEnum("touch/rotateAction", value: "None")

    try ([
      "appearance/adjustments", "appearance/filter", "appearance/effect",
      "appearance/blur", "appearance/shadow",
      "editor/select",
      "fill/change", "fill/changeType",
      "layer/crop", "layer/move", "layer/resize", "layer/rotate", "layer/flip",
      "layer/opacity", "layer/blendMode", "layer/visibility", "layer/clipping",
      "lifecycle/destroy", "lifecycle/duplicate",
      "stroke/change", "shape/change",
      "text/edit", "text/character",
    ]).forEach { scope in
      try engine.editor.setGlobalScope(key: scope, value: .defer)
    }
  }

  /// Loads the built-in empty apparel scene.
  static let defaultCreateScene: OnCreate.Callback = { engine in
    let sceneURL = Bundle(for: ApparelEditorConfiguration.self).url(
      forResource: "apparel-ui-b-empty",
      withExtension: "scene",
    )!
    try await engine.scene.load(from: sceneURL)
  }

  /// Registers all default and demo asset sources, plus text and photo roll sources.
  static let defaultLoadAssetSources: OnCreate.Callback = { engine in
    let assetSources: [String: URL] = [
      Engine.DefaultAssetSource.sticker.rawValue: Engine.assetBaseURL,
      Engine.DefaultAssetSource.vectorPath.rawValue: Engine.assetBaseURL,
      Engine.DefaultAssetSource.filterLut.rawValue: Engine.assetBaseURL,
      Engine.DefaultAssetSource.filterDuotone.rawValue: Engine.assetBaseURL,
      Engine.DefaultAssetSource.colorsDefaultPalette.rawValue: Engine.assetBaseURL,
      Engine.DefaultAssetSource.effect.rawValue: Engine.assetBaseURL,
      Engine.DefaultAssetSource.blur.rawValue: Engine.assetBaseURL,
      Engine.DefaultAssetSource.typeface.rawValue: Engine.assetBaseURL,
      Engine.DefaultAssetSource.cropPresets.rawValue: Engine.assetBaseURL,
      Engine.DefaultAssetSource.pagePresets.rawValue: Engine.assetBaseURL,

      Engine.DemoAssetSource.image.rawValue: Engine.assetBaseURL,
      Engine.DemoAssetSource.textComponents.rawValue: Engine.assetBaseURL,
    ]

    try await withThrowingTaskGroup(of: Void.self) { group in
      for assetSource in assetSources {
        group.addTask {
          try await engine.populateAssetSource(id: assetSource.key, baseURL: assetSource.value)
        }
      }
      try await group.waitForAll()
    }

    try engine.asset.addLocalSource(
      sourceID: Engine.DemoAssetSource.imageUpload.rawValue,
      supportedMimeTypes: Engine.DemoAssetSource.imageUpload.mimeTypes,
    )

    try await engine.asset.addSource(TextAssetSource(engine: engine))
    try engine.asset.addSource(PhotoRollAssetSource(engine: engine))
  }

  /// Configures apparel-specific outline and page clipping behavior.
  static let defaultPostCreateScene: OnCreate.Callback = { engine in
    guard let scene = try engine.block.find(byType: .scene).first,
          let page = try engine.scene.getPages().first
    else {
      return
    }

    // Add outline block for apparel shape visualization.
    _ = try ApparelEditorConfiguration.addOutline(
      "always-on-top-page-outline", for: page, to: scene, engine: engine,
    )
    try ApparelEditorConfiguration.showOutline(false, engine: engine)

    // Temporarily enable scopes to configure page clipping.
    let isFillChangeEnabled = try engine.block.isScopeEnabled(page, key: "fill/change")
    let isLayerClippingEnabled = try engine.block.isScopeEnabled(page, key: "layer/clipping")
    try engine.block.setScopeEnabled(page, key: "fill/change", enabled: true)
    try engine.block.setScopeEnabled(page, key: "layer/clipping", enabled: true)

    // Configure page appearance and clipping for apparel editing.
    try engine.editor.setSettingBool("page/dimOutOfPageAreas", value: false)
    try engine.block.setClipped(page, clipped: true)
    try engine.block.setBool(page, property: "fill/enabled", value: false)
    try ApparelEditorConfiguration.showOutline(false, engine: engine)

    // Restore original scope states.
    try engine.block.setScopeEnabled(page, key: "fill/change", enabled: isFillChangeEnabled)
    try engine.block.setScopeEnabled(page, key: "layer/clipping", enabled: isLayerClippingEnabled)
  }

  // MARK: - Helpers

  /// Adds an outline block for apparel shape visualization.
  internal static func addOutline(
    _ name: String? = nil,
    for id: DesignBlockID,
    to parent: DesignBlockID,
    engine: Engine,
  ) throws -> DesignBlockID {
    let outline = try engine.block.create(.graphic)
    let rect = try engine.block.createShape(.rect)
    try engine.block.setShape(outline, shape: rect)

    let height = try engine.block.getHeight(id)
    let width = try engine.block.getWidth(id)

    if let name {
      try engine.block.setName(outline, name: name)
    }
    try engine.block.setHeightMode(outline, mode: .absolute)
    try engine.block.setHeight(outline, value: height)
    try engine.block.setWidthMode(outline, mode: .absolute)
    try engine.block.setWidth(outline, value: width)
    try engine.block.appendChild(to: parent, child: outline)

    try engine.block.setBool(outline, property: "fill/enabled", value: false)
    try engine.block.setBool(outline, property: "stroke/enabled", value: true)
    try engine.block.setStrokeStyle(outline, style: .dotted)
    try engine.block.setStrokeWidth(outline, width: 1.0)
    try engine.block.setBlendMode(outline, mode: .difference)
    try engine.block.setScopeEnabled(outline, key: "editor/select", enabled: false)
    if let color = Color(cgColor: CGColor.imgly.white) {
      try engine.block.setColor(outline, property: "stroke/color", color: color)
    }
    return outline
  }

  /// Shows or hides the outline block.
  internal static func showOutline(_ isVisible: Bool, engine: Engine) throws {
    guard let outline = engine.block.find(byName: "always-on-top-page-outline").first else {
      throw EditorError("No outline block was found.")
    }
    try engine.block.setVisible(outline, visible: isVisible)
    // Workaround: Trigger opacity to force refresh on "fast" devices.
    try engine.block.setOpacity(outline, value: isVisible ? 1 : 0)
  }
}

import IMGLYEditor
import IMGLYEngine
import UniformTypeIdentifiers

// MARK: - Default OnExport

extension ApparelEditorConfiguration {
  /// The default export handler.
  ///
  /// Exports the scene as PDF and opens the system share sheet.
  static var defaultOnExportHandler: OnExport.Handler {
    { engine, eventHandler, _ in
      guard let scene = try engine.scene.get() else {
        throw EditorError("No scene was found.")
      }
      let data = try await engine.block.export(scene, mimeType: .pdf) { engine in
        try engine.scene.getPages().forEach {
          try engine.block.setScopeEnabled($0, key: "layer/visibility", enabled: true)
          try engine.block.setVisible($0, visible: true)
        }
      }
      let url = FileManager.default.temporaryDirectory.appendingPathComponent("Export", conformingTo: .pdf)
      try data.write(to: url, options: [.atomic])
      eventHandler.send(.shareFile(url))
    }
  }
}

Build print-ready t-shirt designs with a focused mobile UI. Runs entirely on the mobile device with no server dependencies.

T-Shirt Designer starter kit screenshot

10 mins

estimated time

Download

GitHub

Pre-Requisites#

This guide assumes basic familiarity with iOS and Swift. You will need:

Latest Xcode
Swift 5.9 or later
iOS 16.0+

New Project

Existing Project

Get Started#

Start with a complete, runnable iOS starter kit project.

Step 1: Clone the Repository#

git clone -b v1.73.0 https://github.com/imgly/starterkit-apparel-editor-ios.git
cd starterkit-apparel-editor-ios

Step 2: Open and Run#

Open the project in Xcode and run on a simulator or connected device:

Open starterkit-apparel-editor-ios.xcodeproj in Xcode
Select your target device or simulator
Press ⌘R to build and run

The sample app shows a “Launch Editor” button. Tapping it presents the apparel editor:

var body: some View {
  Editor(settings)
    .imgly.configuration {
      ApparelEditorConfiguration()
    }
}

Get Started#

Integrate the starter kit files into your existing iOS app.

Step 1: Add the IMG.LY Swift Package#

Add the CE.SDK dependency via Swift Package Manager:

In Xcode, go to File → Add Package Dependencies…
Enter the repository URL:
```
https://github.com/imgly/IMGLYUI-swift
```
Select version 1.73.0 and add the IMGLYApparelEditor product to your target

Step 2: Copy the Starter Kit Files#

Download and extract the starter kit files into your project:

repo="starterkit-apparel-editor-ios"
version="1.73.0"
curl -L "https://codeload.github.com/imgly/${repo}/tar.gz/refs/heads/v${version}" | tar -xz --strip-components=1 "${repo}-v${version}/starter-kit"

Step 3: Add Files to Your Xcode Project#

Drag the starter-kit/ folder into your Xcode project. Make sure “Copy items if needed” is checked and the files are added to your app target.

Step 4: Launch the Editor From Your UI#

Present the editor from any SwiftUI view:

Editor(settings)
  .imgly.configuration {
    ApparelEditorConfiguration()
  }

The full implementation of the starter kit lives in the starter-kit/ folder:

starter-kit/
├── ApparelEditorStarterKit.swift       # SwiftUI view that launches the editor
├── ApparelEditorConfiguration.swift    # Editor configuration (callbacks + UI components)
├── callbacks/
│   ├── OnCreate+Apparel.swift           # Editor initialization logic (outline setup)
│   ├── OnExport+Apparel.swift           # Export flow and handling (PDF)
│   └── OnChanged+Apparel.swift          # Gesture, page, and view mode handling
└── components/
    ├── CanvasMenu+Apparel.swift         # Canvas menu configuration
    ├── Dock+Apparel.swift               # Dock configuration
    ├── InspectorBar+Apparel.swift       # Inspector bar configuration
    └── NavigationBar+Apparel.swift      # Navigation bar configuration

Configuring the Starter Kit#

The starter kit provides a generic structure and behavior that you can customize to match your needs. Since the implementation is part of your codebase, you can add, remove, or modify functionality as you wish.

The entry point is ApparelEditorStarterKit.swift, which creates the Editor view and applies the configuration:

Editor(settings)
  .imgly.configuration {
    ApparelEditorConfiguration()
  }

You can configure the editor based on your business logic — for example, loading a scene from a previous editing session or displaying different UI for different users. Add properties to ApparelEditorStarterKit and use them in the .imgly.onCreate callback to customize scene loading or other behavior.

Set Up a Scene#

The scene setup logic is located in OnCreate+Apparel.swift as part of the defaultCreateScene callback:

let sceneURL = Bundle(for: ApparelEditorConfiguration.self).url(
  forResource: "apparel-ui-b-empty",
  withExtension: "scene",
)!
try await engine.scene.load(from: sceneURL)

CE.SDK offers multiple ways to load a scene into the editor — from a template archive, a blank canvas, or a .scene file.

Customize Assets#

The asset source setup is located in OnCreate+Apparel.swift as part of the defaultLoadAssetSources callback. Enable or disable individual sources:

let assetSources: [String: URL] = [
  Engine.DefaultAssetSource.sticker.rawValue: Engine.assetBaseURL,
  Engine.DefaultAssetSource.vectorPath.rawValue: Engine.assetBaseURL,
  Engine.DefaultAssetSource.filterLut.rawValue: Engine.assetBaseURL,
  Engine.DefaultAssetSource.filterDuotone.rawValue: Engine.assetBaseURL,
  Engine.DefaultAssetSource.colorsDefaultPalette.rawValue: Engine.assetBaseURL,
  Engine.DefaultAssetSource.effect.rawValue: Engine.assetBaseURL,
  Engine.DefaultAssetSource.blur.rawValue: Engine.assetBaseURL,
  Engine.DefaultAssetSource.typeface.rawValue: Engine.assetBaseURL,
  Engine.DefaultAssetSource.cropPresets.rawValue: Engine.assetBaseURL,
  Engine.DefaultAssetSource.pagePresets.rawValue: Engine.assetBaseURL,

  Engine.DemoAssetSource.image.rawValue: Engine.assetBaseURL,
  Engine.DemoAssetSource.textComponents.rawValue: Engine.assetBaseURL,
]

try await withThrowingTaskGroup(of: Void.self) { group in
  for assetSource in assetSources {
    group.addTask {
      try await engine.populateAssetSource(id: assetSource.key, baseURL: assetSource.value)
    }
  }
  try await group.waitForAll()
}

try engine.asset.addLocalSource(
  sourceID: Engine.DemoAssetSource.imageUpload.rawValue,
  supportedMimeTypes: Engine.DemoAssetSource.imageUpload.mimeTypes,
)

try await engine.asset.addSource(TextAssetSource(engine: engine))
try engine.asset.addSource(PhotoRollAssetSource(engine: engine))

For production deployments, self-hosting assets is required—the IMG.LY CDN is intended for development only. See Serve Assets for downloading assets, configuring baseURL and excluding unused sources to optimize load times.

Customize Export Functionality#

Export handling logic is located in OnExport+Apparel.swift as part of the onExport callback.

The default implementation exports the scene as PDF and opens the system share sheet:

guard let scene = try engine.scene.get() else {
  throw EditorError("No scene was found.")
}
let data = try await engine.block.export(scene, mimeType: .pdf) { engine in
  try engine.scene.getPages().forEach {
    try engine.block.setScopeEnabled($0, key: "layer/visibility", enabled: true)
    try engine.block.setVisible($0, visible: true)
  }
}
let url = FileManager.default.temporaryDirectory.appendingPathComponent("Export", conformingTo: .pdf)
try data.write(to: url, options: [.atomic])
eventHandler.send(.shareFile(url))

Customize (Optional)#

Base URL#

The starter kit uses Engine.assetBaseURL by default, which points to https://cdn.img.ly/packages/imgly/cesdk-engine/1.73.0/assets. To self-host assets, download the asset zip file and pass a custom baseURL to your EngineSettings.

Color Scheme#

CE.SDK supports light and dark modes out of the box, plus automatic system preference detection. Apply SwiftUI’s .preferredColorScheme modifier to the Editor view to switch themes.

See Theming for more details.

Localization#

See Localization for supported languages, adding support for new languages, and replacing existing keys.

UI Layout#

All configurable components are located in the components/ folder:

CanvasMenu+Apparel.swift — see Canvas Menu for full configuration options
Dock+Apparel.swift — see Dock for full configuration options
InspectorBar+Apparel.swift — see Inspector Bar for full configuration options
NavigationBar+Apparel.swift — see Navigation Bar for full configuration options

Troubleshooting#

Editor doesn’t load#

Check onCreate: Ensure the onCreate callback loads a scene successfully
Verify the baseURL: Assets must be accessible from the CDN or your self-hosted location
Check Xcode console: Look for errors in the Xcode debug console

Assets don’t appear#

Check network requests: Make sure the device or simulator is connected to the internet
Self-host assets for production: See Serve Assets to host assets on your infrastructure
Check Xcode console: Look for errors in the Xcode debug console

Export fails or produces blank documents#

Wait for content to load: Ensure all elements are fully loaded before exporting
Check Xcode console: Look for errors in the Xcode debug console

Watermark appears in production#

Add your license key: Set the license property in your EngineSettings
Sign up for a trial: Get a free trial license at img.ly/forms/free-trial

Next Steps#

Configuration – Complete list of initialization options
Serve Assets – Self-host engine assets for production
Theming – Customize colors and appearance
Localization – Add translations and language support

T-Shirt Designer in iOS

Pre-Requisites#

Get Started#

Step 1: Clone the Repository#

Step 2: Open and Run#

Get Started#

Step 1: Add the IMG.LY Swift Package#

Step 2: Copy the Starter Kit Files#

Step 3: Add Files to Your Xcode Project#

Step 4: Launch the Editor From Your UI#

Configuring the Starter Kit#

Set Up a Scene#

Customize Assets#

Customize Export Functionality#

Customize (Optional)#

Base URL#

Color Scheme#

Localization#

UI Layout#

Troubleshooting#

Editor doesn’t load#

Assets don’t appear#

Export fails or produces blank documents#

Watermark appears in production#

Next Steps#