RichText

<p align="center"> <a href="https://swift.org/"> <img src="https://img.shields.io/badge/Swift-5.9+-F05138?labelColor=303840" alt="Swift: 5.9+"> </a> <a href="https://www.apple.com/ios/"> <img src="https://img.shields.io/badge/iOS-15.0+-007AFF?labelColor=303840" alt="iOS: 15.0+"> </a> <a href="https://www.apple.com/macos/"> <img src="https://img.shields.io/badge/macOS-12.0+-007AFF?labelColor=303840" alt="macOS-12.0+"> </a> <a href="https://developer.apple.com/xcode/"> <img src="https://img.shields.io/badge/Xcode-16+-blue?labelColor=303840" alt="Xcode: 16+"> </a> <a href="https://github.com/NuPlay/RichText/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/NuPlay/RichText" alt="License"> </a> <a href="https://github.com/NuPlay/RichText/releases"> <img src="https://img.shields.io/github/v/release/NuPlay/RichText" alt="Release"> </a> </p>

A modern, powerful, and type-safe SwiftUI component for rendering HTML content with extensive styling options, async/await support, media interaction, and comprehensive error handling. Built for Swift 5.9+ and optimized for iOS 15.0+ and macOS 12.0+.

| <img width="1440" alt="Light Mode Screenshot" src="https://user-images.githubusercontent.com/73557895/131149958-bbc28435-02e2-4a02-8ad5-43627cd333e0.png"> | <img width="1440" alt="Dark Mode Screenshot" src="https://user-images.githubusercontent.com/73557895/131149926-211e2111-6d6e-4aac-94b8-44c7230b6244.png"> | |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------: |:------------------------------------------------------------------------------------------------------------------------------: | | Light Mode | Dark Mode |

---

Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📦 Installation
• 📚 Complete API Reference
• 🆕 What's New in v3.0.0
• 🔧 Advanced Usage
• 💡 Examples
• 🐛 Troubleshooting
• 📖 Migration Guide
• 🤝 Contributing

---

✨ Features

🚀 v3.0.0 - Modern Architecture

• ⚡ Async/Await Support: Modern Swift concurrency for better performance
• 🛡️ Type Safety: Comprehensive Swift type safety with robust error handling
• 🧪 Swift Testing: Modern testing framework with extensive test coverage
• 🔧 Backward Compatible: 100% compatibility with v2.x while providing modern APIs

📱 Platform Support

• 📱 Cross-platform: iOS 15.0+ and macOS 12.0+ with Swift 5.9+
• 🎨 Theme Support: Automatic light/dark mode with custom color schemes
• 🔤 Typography: System fonts, custom fonts, monospace, italic, and Dynamic Type support

🎛️ Rich Features

• 🖼️ Interactive Media: Click events for images/videos with custom handling
• 🔗 Smart Link Management: Safari, SFSafariView, and custom link handlers
• 🎨 Advanced Styling: Type-safe background colors, CSS customization
• 📐 Responsive Layout: Dynamic height calculation with smooth transitions
• 🔄 Loading States: Configurable placeholders with animation support
• 🌐 HTML5 Complete: Full support for modern semantic elements
• 🚨 Error Handling: Comprehensive error types with custom callbacks

---

🚀 Quick Start

Basic Usage

The simplest way to get started with RichText:

import SwiftUI
import RichText

struct ContentView: View {
    let htmlContent = """
        <h1>Welcome to RichText</h1>
        <p>A powerful HTML renderer for SwiftUI.</p>
    """
    
    var body: some View {
        ScrollView {
            RichText(html: htmlContent)
        }
    }
}

Enhanced Example

Add styling, media handling, and error handling:

struct ContentView: View {
    let htmlContent = """
        <h1>Welcome to RichText</h1>
        <p>A powerful HTML renderer with <strong>extensive customization</strong>.</p>
        <img src="https://via.placeholder.com/300x200" alt="Sample Image">
        <p><a href="https://github.com/NuPlay/RichText">Visit our GitHub</a></p>
    """
    
    var body: some View {
        ScrollView {
            RichText(html: htmlContent)
                .colorScheme(.auto)                    // Auto light/dark mode
                .lineHeight(170)                       // Line height percentage
                .imageRadius(12)                       // Rounded image corners
                .transparentBackground()               // Transparent background
                .placeholder {                         // Loading Placeholder
                    Text("Loading email...")
                }
                .onMediaClick { media in               // Handle media clicks
                    switch media {
                    case .image(let src):
                        print("Image clicked: \(src)")
                    case .video(let src):
                        print("Video clicked: \(src)")
                    }
                }
                .onError { error in                    // Handle errors
                    print("RichText error: \(error)")
                }
        }
    }
}

---

📦 Installation

Swift Package Manager (Recommended)

1. In Xcode, select File → Add Package Dependencies...
2. Enter the repository URL:

   https://github.com/NuPlay/RichText.git
   

3. Select version rule: "Up to Next Major Version" from "3.0.0"
4. Click Add Package

Manual Package.swift

Add RichText to your Package.swift:

dependencies: [
    .package(url: "https://github.com/NuPlay/RichText.git", .upToNextMajor(from: "3.0.0"))
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: ["RichText"]
    )
]

---

📚 Complete API Reference

Core Components

RichText Initializers

// Basic initializer
RichText(html: String)

// With configuration
RichText(html: String, configuration: Configuration)

// With placeholder
RichText(html: String, placeholder: AnyView?)

// Full initializer
RichText(html: String, configuration: Configuration, placeholder: AnyView?)

Styling Modifiers

Background Colors

// Recommended approaches (v3.0.0+)
.transparentBackground()                    // Transparent (default)
.backgroundColor(.system)                   // System default (white/black)
.backgroundColorHex("FF0000")              // Hex color
.backgroundColorSwiftUI(.blue)             // SwiftUI Color
.backgroundColor(.color(.green))           // Using BackgroundColor enum

// Legacy approach (still works, but deprecated)
.backgroundColor("transparent")             // Deprecated but backward compatible

Typography & Colors

// Font configuration
.fontType(.system)                         // System font (default)
.fontType(.monospaced)                     // Monospaced font
.fontType(.italic)                         // Italic font
.fontType(.customName("Helvetica"))        // Custom font by name
.fontType(.custom(UIFont.systemFont(ofSize: 16))) // Custom UIFont (iOS only)

// Text colors - Modern API (v3.0.0+)
.textColor(light: .primary, dark: .primary)         // Modern semantic naming

// Legacy text colors (deprecated but supported)
.foregroundColor(light: .primary, dark: .primary)   // SwiftUI Colors (deprecated)
.foregroundColor(light: UIColor.black, dark: UIColor.white) // UIColors (deprecated)
.foregroundColor(light: NSColor.black, dark: NSColor.white) // NSColors (deprecated)

// Link colors
.linkColor(light: .blue, dark: .cyan)      // SwiftUI Colors
.linkColor(light: UIColor.blue, dark: UIColor.cyan) // UIColors

// Color enforcement
.colorPreference(forceColor: .onlyLinks)   // Force only link colors (default)
.colorPreference(forceColor: .all)         // Force all colors
.colorPreference(forceColor: .none)        // Don't force any colors

Layout & Spacing

.lineHeight(170)                           // Line height percentage (default: 170)
.imageRadius(12)                           // Image border radius in points (default: 0)
.colorScheme(.auto)                        // .auto (default), .light, .dark
.forceColorSchemeBackground(true)          // Force background color override

Link Behavior

.linkOpenType(.Safari)                     // Open in Safari (default)
.linkOpenType(.SFSafariView())            // Open in SFSafariViewController (iOS)
.linkOpenType(.SFSafariView(               // Advanced SFSafariView config
    configuration: config,
    isReaderActivated: true,
    isAnimated: true
))
.linkOpenType(.custom { url in             // Custom link handler
    // Handle URL yourself
})
.linkOpenType(.none)                       // Don't handle link taps

Advanced Features

Loading States

// Loading placeholders (Modern approach - recommended)
.placeholder {                             // Custom placeholder view
    HStack(spacing: 8) {
        ProgressView()
            .scaleEffect(0.8)
        Text("Loading content...")
            .foregroundColor(.secondary)
    }
    .frame(minHeight: 60)
}

// Deprecated methods (still supported for backward compatibility)
.loadingPlaceholder("Loading...")          // Deprecated - use placeholder {}
.loadingText("Please wait...")             // Deprecated - use placeholder {}

// Loading transitions
.loadingTransi