FREE: Read a new Swift article every day – click here! >>

NSAttributedString by example

Paul Hudson       @twostraws

Regular Swift strings are great for storing plain text, but as soon as you want formatting, images, or interactivity you need to reach for NSAttributedString - Foundation’s all-in-one string handling class. These are used in lots of places in iOS, but you're most likely to want to use them with UILabel and UITextView – both of which accept attributed strings directly.

In this article I want to walk you through some examples of what NSAttributedString is capable of: creating strings by hand, adding and enumerating attributes, adding links and images, and more. All these code samples are written to work with a Swift playground, which is a particularly good place to try out attributed strings because Xcode can render a preview of how the string looks.

Creating attributed strings

Let’s start with the most trivial attributed string: one that holds a regular string with no special styling. Try this in a playground:

let quote = "Haters gonna hate"
let attributedQuote = NSAttributedString(string: quote)

When that runs, click the preview button for attributedQuote and you should be able to preview it. It doesn’t look special – in fact, it looks just like a regular string – but that’s because we haven’t applied any styling yet.

Try this instead:

let quote = "Haters gonna hate"
let font = UIFont.systemFont(ofSize: 72)
let attributes = [NSAttributedStringKey.font: font]
let attributedQuote = NSAttributedString(string: quote, attributes: attributes)

Now we’re asking for the same text to be rendered in a 72-point font, so your preview should be much larger.

What you put in the attributes is down to how the string should look. For example, this will color the text red:

let font = UIFont.systemFont(ofSize: 72)
let attributes: [NSAttributedStringKey: Any] = [
    .font: font,
    .foregroundColor: UIColor.red,
]

Alternatively, this will color the text white and give it a red glow:

let font = UIFont.systemFont(ofSize: 72)
let shadow = NSShadow()
shadow.shadowColor = UIColor.red
shadow.shadowBlurRadius = 5

let attributes: [NSAttributedStringKey: Any] = [
    .font: font,
    .foregroundColor: UIColor.white,
    .shadow: shadow
]

If you want to adjust paragraph-level settings - text alignment, indents, line spacing, and so on – this is done using a separate type called NSMutableParagraphStyle. For example, this creates and applies a paragraph style to make our text centered and have the first line in every paragraph indented by five points:

let font = UIFont.systemFont(ofSize: 72)
let paragraphStyle = NSMutableParagraphStyle()
paragraphStyle.alignment = .center
paragraphStyle.firstLineHeadIndent = 5.0

let attributes: [NSAttributedStringKey: Any] = [
    .font: font,
    .foregroundColor: UIColor.blue,
    .paragraphStyle: paragraphStyle
]

let attributedQuote = NSAttributedString(string: quote, attributes: attributes)

Modifying existing attributed strings

All the above is about creating an attribute string from scratch, but often you’ll want to take an existing attributed string and modify it. For example, if you have some text and the user wants to make part of it bold – rather than create the whole thing from scratch you’ll want to modify what you have.

Let’s start with our basic string again:

let quote = "Haters gonna hate"
let attributedQuote = NSMutableAttributedString(string: quote)

Notice that uses an NSMutableAttributedString now – it’s an attributed string we can modify. Thanks to the way classes work, we can modify this object even though it’s declared as a constant using let.

If we wanted to make the word “gonna” red, we’d call the addAttribute() method of that attributed string, like this:

attributedQuote.addAttribute(.foregroundColor, value: UIColor.red, range: NSRange(location: 7, length: 5))

Yes, that uses NSRange to specify string ranges, which is unfortunate but unavoidable.

If you want to add multiple attributes at the same time, you should use addAttributes instead – it uses the same dictionary approach we used earlier. For example, this will apply a green background color and 10 points of kerning (letter spacing) to the word “Haters”:

let attributes: [NSAttributedStringKey: Any] = [.backgroundColor: UIColor.green, NSAttributedStringKey.kern: 10]
attributedQuote.addAttributes(attributes, range: NSRange(location: 0, length: 6))

While this approach isn’t hard to use – and it’s certainly efficient – I nearly always find it easier to create multiple independent attributed strings then join them together. This approach is both a little slower and a little more memory-intensive, but I find it easier to grasp when working with complex string layouts.

So, the complete code would look like this:

let quote = "Haters gonna hate"

let firstAttributes: [NSAttributedStringKey: Any] = [.backgroundColor: UIColor.green, NSAttributedStringKey.kern: 10]
let secondAttributes = [NSAttributedStringKey.foregroundColor: UIColor.red]

let firstString = NSMutableAttributedString(string: "Haters ", attributes: firstAttributes)
let secondString = NSAttributedString(string: "gonna ", attributes: secondAttributes)
let thirdString = NSAttributedString(string: "hate")

firstString.append(secondString)
firstString.append(thirdString)

This approach segments work into simpler chunks, which means I can in turn compose new attributed strings by mixing and matching various function calls.

Loading an attributed string from HTML

An alternative way to create attributed strings is to have iOS parse some HTML. Although only a subset of styles are supported, it should be enough to handle fonts, sizes, and colors just fine.

For example, we could define some HTML using inline CSS to make a paragraph blue:

let html = """
<html>
<body>
<p style="color: blue;">This is blue!</p>
</body>
</html>
"""

We could then convert that to an instance of Data so it can be read into an attributed string:

let data = Data(html.utf8)

Finally, we can load that data into an NSAttributedString, telling it that we’re using HTML for the document type:

if let attributedString = try? NSAttributedString(data: data, options: [.documentType: NSAttributedString.DocumentType.html], documentAttributes: nil) {
    // use your attributed string somehow
}

Enumerating attributes

If you have an attributed string someone else made – for example reading page text from a PDFView – you can loop over all the attributes to figure out where they are and what they contain.

For example, here’s some code that creates the string “the cat sat on the mat”, where the first, third, and fifth words are larger than the others:

let sentence = "the cat sat on the mat"
let regularAttributes = [NSAttributedStringKey.font: UIFont.systemFont(ofSize: 12)]
let largeAttributes = [NSAttributedStringKey.font: UIFont.boldSystemFont(ofSize: 24)]
let attributedSentence = NSMutableAttributedString(string: sentence, attributes: regularAttributes)

attributedSentence.setAttributes(largeAttributes, range: NSRange(location: 0, length: 3))
attributedSentence.setAttributes(largeAttributes, range: NSRange(location: 8, length: 3))
attributedSentence.setAttributes(largeAttributes, range: NSRange(location: 15, length: 3))

We could enumerate over the font attribute for that string, check to see whether the font is bold, and if it is also color that section red. This is all done using the enumerateAttribute() method: it will find all instances of the attribute you requested, passing them to you one by one along with their range and a stop variable. If you set the stop variable to true, the loop ends.

Here’s that in code:

attributedSentence.enumerateAttribute(.font, in: NSRange(0..<attributedSentence.length)) { value, range, stop in
    if let font = value as? UIFont {
        // make sure this font is actually bold
        if font.fontDescriptor.symbolicTraits.contains(.traitBold) {
            // it's bold, so make it red too
            attributedSentence.addAttribute(.foregroundColor, value: UIColor.red, range: range)
        }
    }
}

There’s also a more general enumerateAttributes() method that gives you all attributes in a specific range.

Placing an image inside an attributed string

So far you might be thinking that attributed strings seem quite easy, but let’s mix things up a little by adding images right inside a string. This is best done inside an app project so that you can load image files more easily.

First, create a regular mutable attributed string with some content:

let fullString = NSMutableAttributedString(string: "Your rank: ")

Second, create an instance of NSTextAttachment – a class specifically designed to let us attach images to attributed strings”

let image1Attachment = NSTextAttachment()
image1Attachment.image = UIImage(named: "rank-major.png")

Third, we can wrap that attachment inside its own attributed string so we can append it to the previous string:

let image1String = NSAttributedString(attachment: image1Attachment)

Finally, we can add the NSTextAttachment wrapper to our full string:

fullString.append(image1String)

That’s it – an image inside our attributed string!

Placing a hyperlink inside an attributed string

Web links are just like any other attributed string attribute, meaning that you can add NSAttributedStringKey.link to any range of your string, along with a URL that should be shown when the link is clicked.

For example:

let attributedString = NSMutableAttributedString(string: "Want to learn iOS? You should visit the best source of free iOS tutorials!")
attributedString.addAttribute(.link, value: "https://www.hackingwithswift.com", range: NSRange(location: 19, length: 55))

Note: this just creates the link, it doesn’t add styling for it. Links will appear blue and underlined by default, but you can set the linkTextAttributes attributed of your text view to whatever attributes you want.

 

MASTER SWIFT NOW
Buy Testing Swift Buy Practical iOS 12 Buy Pro Swift Buy Swift Design Patterns Buy Swift Coding Challenges Buy Server-Side Swift (Vapor Edition) Buy Server-Side Swift (Kitura Edition) Buy Hacking with macOS Buy Advanced iOS Volume One Buy Advanced iOS Volume Two Buy Hacking with watchOS Buy Hacking with tvOS Buy Hacking with Swift Buy Dive Into SpriteKit Buy Swift in Sixty Seconds Buy Objective-C for Swift Developers Buy Beyond Code

About the author

Paul Hudson is the creator of Hacking with Swift, the most comprehensive series of Swift books in the world. He's also the editor of Swift Developer News, the maintainer of the Swift Knowledge Base, and Mario Kart world champion. OK, so that last part isn't true. If you're curious you can learn more here.

Was this page useful? Let me know!

Average rating: 4.9/5

Click here to visit the Hacking with Swift store >>