FormattedListKit: Elegant List Displays Made Easy

When developing iOS and macOS applications, formatting lists is a common requirement. Whether it's terms and conditions, setting options, or tutorial steps, we often need to present ordered or unordered list content. However, Apple's native frameworks have relatively limited support for list formatting, which often puts developers in a dilemma: existing solutions aren't perfect, while heavier solutions seem like overkill.

To solve this problem, I developed FormattedListKit, a lightweight yet fully-featured Swift Package specifically designed for creating beautifully formatted ordered and unordered lists.

Why FormattedListKit?

I've tried several existing solutions, but wasn't fully satisfied with any of them:

Using Markdown: iOS/macOS has limited native support for Markdown. Although AttributedString can process markdown syntax, it performs poorly when it comes to list formatting.
Using third-party Markdown packages: Introducing a complete Markdown parsing engine just to display lists seems bloated and over-engineered.
Using WebView to display HTML: This requires converting simple text lists to HTML first, and WebViews consume more resources.
Custom implementation (handling markers and items separately): Highly flexible, but requires dealing with relatively complex layout logic.

Based on these pain points, FormattedListKit was born. It provides a simple yet powerful solution that allows developers to create beautiful lists with just a few lines of code.

Core Features of FormattedListKit

FormattedListKit's design philosophy is "simple and focused" - it concentrates on solving the specific problem of list formatting. Here are its main features:

1. Support for Multiple List Types

Ordered lists: Supports integers (1. 2. 3.), Roman numerals (i. ii. iii. or I. II. III.), and letters (a. b. c. or A. B. C.)
Unordered lists: Supports bullets (•), hollow circles (◦), squares (▪), and custom symbols

2. Flexible Formatting Options

Marker alignment: Supports left or right alignment of markers
Custom font: Allows setting font for list items
Proper indentation: Ensures multi-line text is correctly aligned, improving readability

3. Simple API

FormattedListKit provides a simple and intuitive API through NSAttributedString extensions, creating complete lists with just one function call.

let items = ["First item", "Second very long item that needs to wrap to the next line", "Third item"]
let attributedString = NSAttributedString.createList(
    for: items,
    type: .ordered(style: .decimal),
    font: .systemFont(ofSize: 16),
    markerAlignment: .right
)

// Set the formatted list to a UILabel or UITextView
myTextView.attributedText = attributedString

4. Cross-platform Support

FormattedListKit supports both iOS and macOS platforms, ensuring consistent list display experiences across different devices.

How to Use FormattedListKit in Your Project

Add FormattedListKit to your project using Swift Package Manager, then just import FormattedListKit:

dependencies: [
    .package(url: "https://github.com/chiahsien/FormattedListKit.git", from: "1.0.0")
]

Practical Use Cases

FormattedListKit is particularly suitable for:

User agreements and terms: Clearly formatted lists of terms, improving readability
Tutorials and guides: Step-by-step instructions or helpful tips
Content display: Any place where lists need to be displayed

Conclusion

FormattedListKit was born from practical development needs, aiming to solve a seemingly simple but actually annoying problem: how to elegantly display formatted lists. By focusing on this specific functionality, it provides a lightweight but complete solution that both avoids reinventing the wheel and doesn't require overly large dependencies.

Check out FormattedListKit, and please consider contributing through Issues or PRs on GitHub 😁

Nelson