1. Create the view

import TTGTags

let tagView = TextTagCollectionView()
tagView.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(tagView)

NSLayoutConstraint.activate([
    tagView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16),
    tagView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
    tagView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 24)
])

2. Build content plus style

Each TextTag is built from content and style. The same model also carries selection state, accessibility metadata, and optional attachment data.

let content = TextTagStringContent(text: "Swift")
content.textFont = .boldSystemFont(ofSize: 14)
content.textColor = .white

let style = TextTagStyle()
style.enableGradientBackground = true
style.gradientBackgroundStartColor = .systemBlue
style.gradientBackgroundEndColor = .systemPurple
style.cornerRadius = 12
style.extraSpace = CGSize(width: 14, height: 8)

let tag = TextTag(content: content, style: style)
tagView.add(tag: tag)
tagView.reload()

3. Add selected states

selectedStyle is applied automatically when a tag is selected. Use selectionLimit and the delegate callbacks for app-specific behavior.

let selectedStyle = TextTagStyle()
selectedStyle.backgroundColor = .systemOrange
selectedStyle.cornerRadius = 12
selectedStyle.extraSpace = CGSize(width: 14, height: 8)

tag.selectedStyle = selectedStyle
tagView.selectionLimit = 3
tagView.delegate = self

4. Control layout behavior

Use the same view for normal wrapping tag clouds, fill-width rows, or horizontal filter bars.

tagView.alignment = .fillByExpandingWidth
tagView.horizontalSpacing = 8
tagView.verticalSpacing = 8
tagView.contentInset = UIEdgeInsets(top: 12, left: 12, bottom: 12, right: 12)

tagView.scrollDirection = .horizontal
tagView.numberOfLines = 2
tagView.showsHorizontalScrollIndicator = false

tagView.reload()

Objective-C

#import <TTGTags/TTGTags-Swift.h>

TTGTextTagCollectionView *tagView = [[TTGTextTagCollectionView alloc] initWithFrame:self.view.bounds];
[self.view addSubview:tagView];

TTGTextTagStringContent *content = [TTGTextTagStringContent contentWithText:@"Hello"];
TTGTextTagStyle *style = [TTGTextTagStyle new];
style.backgroundColor = UIColor.systemBlueColor;
style.cornerRadius = 10;
style.extraSpace = CGSizeMake(12, 8);

TTGTextTag *tag = [TTGTextTag tagWithContent:content style:style];
[tagView addTag:tag];
[tagView reload];

Concepts

Understanding these 4 building blocks will help you use the library effectively:

Key rule: always call reload() after adding, removing, or updating tags.

Visual Assets

• Promo poster: Resources/promo_poster.png
• Quick Start images: Resources/quick_start_01_create.png, Resources/quick_start_02_style.png, Resources/quick_start_03_selection.png, Resources/quick_start_04_layout.png
• Concepts image: Resources/concepts_poster.png
• Review HTML: Resources/promo_poster.html, Resources/quick_start_01_create.html, Resources/quick_start_02_style.html, Resources/quick_start_03_selection.html, Resources/quick_start_04_layout.html
• Regenerate PNG assets with node Resources/render_readme_images.mjs.

Architecture at a Glance

The architecture poster is generated from Resources/architecture_poster.html. It summarizes the Swift-first architecture, Objective-C compatibility layer, pure layout engine, rendering flow, and the cache-aware path used for dense tag lists.

Usage

Delegate

tagView.delegate = self

// TextTagCollectionViewDelegate
func textTagCollectionView(_ collectionView: TextTagCollectionView,
                           canTapTag tag: TextTag, at index: Int) -> Bool { true }

func textTagCollectionView(_ collectionView: TextTagCollectionView,
                           didTapTag tag: TextTag, at index: Int) {
    print("tapped: \(tag.rightfulContent.contentAttributedString.string), selected: \(tag.selected)")
}

func textTagCollectionView(_ collectionView: TextTagCollectionView,
                           canSwipeSelectTag tag: TextTag, at index: Int) -> Bool { true }

func textTagCollectionView(_ collectionView: TextTagCollectionView,
                           didSwipeSelectTag tag: TextTag, at index: Int) {
    print("swipe selected: \(index)")
}

func textTagCollectionView(_ collectionView: TextTagCollectionView,
                           updateContentSize contentSize: CGSize) {
    // e.g. update a height constraint
}

Content types

// Plain text
let c1 = TextTagStringContent(text: "Hello")
c1.textFont  = .systemFont(ofSize: 14)
c1.textColor = .darkText

// Rich text via NSAttributedString
let attrs: [NSAttributedString.Key: Any] = [
    .foregroundColor: UIColor.systemRed,
    .font: UIFont.boldSystemFont(ofSize: 16)
]
let c2 = TextTagAttributedStringContent(
    attributedText: NSAttributedString(string: "Rich", attributes: attrs)
)

Style properties — TextTagStyle

let style = TextTagStyle()

// Background
style.backgroundColor = .systemBlue
style.textAlignment = .center
style.numberOfLines = 1                  // 0 = unlimited multiline
style.lineBreakMode = .byTruncatingTail

// Gradient background
style.enableGradientBackground        = true
style.gradientBackgroundStartColor    = .systemBlue
style.gradientBackgroundEndColor      = .systemPurple
style.gradientBackgroundStartPoint    = CGPoint(x: 0, y: 0.5)
style.gradientBackgroundEndPoint      = CGPoint(x: 1, y: 0.5)

// Corner (all corners by default; set individual flags for per-corner control)
style.cornerRadius      = 14
style.cornerTopLeft     = true
style.cornerTopRight    = true
style.cornerBottomLeft  = false
style.cornerBottomRight = false

// Border
style.borderWidth = 1
style.borderColor = .white

// Shadow
style.shadowColor   = .black
style.shadowOffset  = CGSize(width: 2, height: 2)
style.shadowRadius  = 2
style.shadowOpacity = 0.3

// Size
style.extraSpace  = CGSize(width: 12, height: 6)  // padding
style.minWidth    = 60      // 0 = no limit
style.maxWidth    = 200
style.exactWidth  = 0       // 0 = auto
style.exactHeight = 32

Layout configuration

tagView.scrollDirection  = .vertical     // .vertical (default) or .horizontal
tagView.alignment        = .left         // see Alignment below
tagView.horizontalDistribution = .rowMajor
tagView.contentVerticalAlignment = .top
tagView.numberOfLines    = 0             // 0 = unlimited
tagView.selectionLimit   = 3             // 0 = unlimited
tagView.horizontalSpacing = 8
tagView.verticalSpacing   = 8
tagView.contentInset      = UIEdgeInsets(top: 8, left: 8, bottom: 8, right: 8)

// AutoLayout manual height
tagView.manualCalculateHeight   = true
tagView.preferredMaxLayoutWidth = 320

// Tap callbacks (no delegate needed)
tagView.onTapBlankArea = { point in print("tapped blank at \(point)") }
tagView.onTapAllArea   = { point in print("tapped anywhere at \(point)") }

Alignment modes

Horizontal rows and vertical placement

// Natural reading order in horizontal multi-line rows (default in 3.1)
tagView.scrollDirection = .horizontal
tagView.numberOfLines = 2
tagView.horizontalDistribution = .rowMajor

// Preserve the old round-robin column-first behavior when needed
tagView.horizontalDistribution = .columnMajor

// Center content inside a fixed-height tag surface
tagView.contentVerticalAlignment = .center

Multiline text tags

let content = TextTagStringContent(text: "Long filter label that can wrap")
let style = TextTagStyle()
style.numberOfLines = 0
style.maxWidth = 180
style.lineBreakMode = .byWordWrapping

let tag = TextTag(content: content, style: style)

Tag model — TextTag

let tag = TextTag()

// Content & style for normal / selected state
tag.content         = TextTagStringContent(text: "Label")
tag.style           = TextTagStyle()
tag.selectedContent = TextTagStringContent(text: "Selected")   // optional, falls back to content copy
tag.selectedStyle   = TextTagStyle()                           // optional, falls back to style copy

// Selection
tag.selected = false
tag.onSelectStateChanged = { selected in print