Attributed String Builders

AttributedString Builder

A simple way to build up attributed strings using result builders from a variety of sources. Based on the episodes from Swift Talk. Here are the things you can embed:

  • Plain strings
  • Markdown
  • Images
  • SwiftUI Views
  • Table support
  • Multi-page PDF export
  • Footnotes

Here's an example showing plain strings, Markdown and SwiftUI views:

var example: some AttributedStringConvertible {
    "Hello, World!"
        .modify { $0.backgroundColor = .yellow }
    This is some markdown with **strong** `code` text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas tempus, tortor eu maximus gravida, ante diam fermentum magna, in gravida ex tellus ac purus.

    - One
    - Two
    - Three

    > A blockquote.
    Embed {
        HStack {
            Image(systemName: "hand.wave")
            Text("Hello from SwiftUI")
   100, height: 50)

You can then turn this example into a multi-page PDF like this:

let data = await example
    .joined(separator: "\n") // join the parts using newlines
    .run(environment: .init(attributes: sampleAttributes)) // turn into a single `NSAttributedString`
    .pdf() // render as PDF
try! data.write(to: .desktopDirectory.appending(component: "out.pdf"))

Here's a larger sample.



The Attributes struct is a value type representing the attributes in an NSAttributedString. During the building of the attributed string, this is passed on through the environment. For example, this is how you can build a simple attributed string using plain strings and .modify:

@AttributedStringBuilder var sample1: some AttributedStringConvertible {
    "World".modify { $0.textColor = .red }


You can turn any string directly into an attributed string. The attributes from the environment are used to do this. You can also modify the environment in a way very similar to what SwiftUI does. For example, you can write "Hello".bold()" to take the current attributes, make them bold, and then render the string "Hello"` using these modified attributes.


You can take any Markdown string and render it into an attributed string as well. For most customization, you can pass in a custom stylesheet. In the Markdown string literal, you can embed other values that convert to AttributedStringConvertible:

@AttributedStringBuilder var sample2: some AttributedStringConvertible {
    This is *Markdown* syntax.

    With \("inline".modify { $0.underlineStyle = .single }) nesting.


You can embed any NSImage into the attributed string, they're rendered as-is.

SwiftUI Views

SwiftUI views can be embedded using the Embed modifier. By default, it proposes nil‚®Čnil to the view, but this can be customized. SwiftUI views are rendered into a PDF context and are embedded as vector graphics.


You can construct tables in attributed strings using the Table support. This interface might still change (ideally, we'd use result builders for this as well).


You can use the environment in a way similar to SwiftUI's Environment to pass values down the tree.


Similar to the environment, you can also thread state through. This is useful (for example) to number footnotes. While the modified environment is always passed to children of the current node, modified state is passed to the next nodes that are rendered.

Swift Talk Episodes


  • Swift Tools 5.7.0
View More Packages from this Author


Last updated: Fri Mar 15 2024 13:03:40 GMT-0900 (Hawaii-Aleutian Daylight Time)