<!--
{
  "availability" : [
    "iOS: 3.2.0 -",
    "iPadOS: 3.2.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSAttributedString",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSAttributedString"
  },
  "title" : "NSAttributedString"
}
-->

# NSAttributedString

A string of text that manages data, layout, and stylistic information for ranges of characters to support rendering.

```
class NSAttributedString
```

## Overview

[`NSAttributedString`](/documentation/Foundation/NSAttributedString) is a type you use to manage strings of stylized Unicode text. In addition to text, an attributed string contains key-value pairs known as *attributes* that specify additional information to apply to ranges of characters within the string. Attributed strings support many different kinds of attributes, including:

- Rendering attributes that specify font, color, kern, ligature, and other details
- Attributes for attachments and adaptive image glyphs
- Semantic attributes such as link URLs or tool-tip information
- Language attributes to support automatic gender agreement and text layout
- Accessibility attributes that provide information for assistive technologies
- Attributes that summarize details of the Markdown import process
- Custom attributes you define for your app

Use attributed strings anywhere you need styled text, or when you need to associate additional information with your text. Because [`NSAttributedString`](/documentation/Foundation/NSAttributedString) is an immutable type, you specify all of the text and attributes for it at creation time and can’t change them later. You can create attributed strings directly from a string of characters and a dictionary of attributes. You can also create attributed strings from the contents of a file, including files that contain RTF, RTFD, HTML, Markdown, or other file formats. If you need to modify the contents of an attributed string later, use the [`NSMutableAttributedString`](/documentation/Foundation/NSMutableAttributedString) type instead.

If you create an [`NSAttributedString`](/documentation/Foundation/NSAttributedString) without any font information, the string’s default font is Helvetica 12-point, which might differ from the default system font for the platform. To change the font, specify a font attribute at creation time.

### Persistence

Be aware of how you persist attributed strings to and from the disk. RTF and RTFD are the preferred format for attributed strings because they offer the best fidelity for reading and writing attribute data. The RTF formats support a large number of standard attributes, and Apple extends the formats to support many Apple-specific attributes. If you define custom attributes for ranges of characters, store them separately alongside the RTF file for your text.

If you work extensively with HTML content, validate the results and performance of import and export operations during testing. WebKit handles the conversion between HTML markup and attributed strings. If an HTML file contains tags or constructs that attributed strings don’t support, the import process ignores them and imports what it can.

When you create an attributed string from Markdown, the system adds presentation intent attributes with information about the original Markdown content. The system doesn’t add style attributes to match the Markdown elements, but the system applies default style information when it renders a string with intent attributes. To change the rendering behavior of your Markdown content, remove the intent attributes and add the style attributes you prefer.

> Important:
> When reading or writing attributed strings, choose methods that return or throw an error, and check any errors you receive. Handling errors is the best way to detect issues with the import or export process and take corrective action.

The methods for reading and writing common file formats also support document attributes. Document attributes aren’t part of the attributed string itself, but accompany the text when you save it to a file. When you read a file, the system returns any document attributes that it finds. Similarly, when you write an attributed string to a file, you can specify the attributes to include. For more information about document attributes, see [`NSAttributedString.DocumentAttributeKey`](/documentation/Foundation/NSAttributedString/DocumentAttributeKey) and [`NSAttributedString.DocumentReadingOptionKey`](/documentation/Foundation/NSAttributedString/DocumentReadingOptionKey).

### System framework interoperability

<doc://com.apple.documentation/documentation/UIKit/textkit> and <doc://com.apple.documentation/documentation/CoreText> use attributed strings extensively during the layout and rendering processes. These technologies use the string’s text and rendering-related attributes to calculate the text metrics needed during layout. Similarly, these technologies apply those same attributes during rendering to give the text its styled appearance. The technologies use only attributes that directly affect the appearance of the text, and ignore most other attributes. For some attributes, the text system adds attributes during rendering as needed. For example, the text system provides default style attributes for text with the [`link`](/documentation/Foundation/NSAttributedString/Key/link) attribute.

<doc://com.apple.documentation/documentation/AppKit> and <doc://com.apple.documentation/documentation/UIKit> also support attributed strings in several ways. Some views and controls in these frameworks have APIs that accept attributed strings, and render the string with its style information. The frameworks also add methods to the [`NSAttributedString`](/documentation/Foundation/NSAttributedString) class that let you draw a styled string directly in one of your custom views. Because these methods use TextKit to draw the string, they recognize the same rendering-related attributes as that technology.

The [`NSAttributedString`](/documentation/Foundation/NSAttributedString) class and its Core Foundation counterpart, <doc://com.apple.documentation/documentation/CoreFoundation/CFAttributedString>, are toll-free bridged, which means you can use the two types interchangeably in your code without losing any text or attribute information.

## Topics

### Creating attributed strings

[Creation methods](/documentation/Foundation/creation-methods)

Create attributed strings from existing content or raw text and apply the initial attributes.

### Exporting the string as data

[`data(from:documentAttributes:)`](/documentation/Foundation/NSAttributedString/data(from:documentAttributes:))

Returns a data object that contains a text stream corresponding to the characters and attributes within the specified range.

[`fileWrapper(from:documentAttributes:)`](/documentation/Foundation/NSAttributedString/fileWrapper(from:documentAttributes:))

Returns a file wrapper object that contains a text stream corresponding to the characters and attributes within the specified range.

[`docFormat(from:documentAttributes:)`](/documentation/Foundation/NSAttributedString/docFormat(from:documentAttributes:))

Returns a data object that contains a Microsoft Word–format stream corresponding to the characters and attributes within the specified range.

[`rtf(from:documentAttributes:)`](/documentation/Foundation/NSAttributedString/rtf(from:documentAttributes:))

Returns a data object that contains an RTF stream corresponding to the characters and attributes within the specified range, omitting all attachment attributes.

[`rtfd(from:documentAttributes:)`](/documentation/Foundation/NSAttributedString/rtfd(from:documentAttributes:))

Returns a data object that contains an RTFD stream corresponding to the characters and attributes within the specified range.

[`rtfdFileWrapper(from:documentAttributes:)`](/documentation/Foundation/NSAttributedString/rtfdFileWrapper(from:documentAttributes:))

Returns a file wrapper object that contains an RTFD document corresponding to the characters and attributes within the specified range.

### Getting the characters

[`string`](/documentation/Foundation/NSAttributedString/string)

The character contents of the attributed string as a string.

[`length`](/documentation/Foundation/NSAttributedString/length)

The length of the attributed string.

[`attributedSubstring(from:)`](/documentation/Foundation/NSAttributedString/attributedSubstring(from:))

Returns an attributed string consisting of the characters and attributes within the specified range in the attributed string.

### Getting font attribute information

[`fontAttributes(in:)`](/documentation/Foundation/NSAttributedString/fontAttributes(in:))

Returns the font attributes in effect for the character at the specified location.

[`rulerAttributes(in:)`](/documentation/Foundation/NSAttributedString/rulerAttributes(in:))

Returns the ruler (paragraph) attributes in effect for the characters within the specified range.

### Getting attributes for a range of text

[`attributes(at:effectiveRange:)`](/documentation/Foundation/NSAttributedString/attributes(at:effectiveRange:))

Returns the attributes for the character at the specified index.

[`attributes(at:longestEffectiveRange:in:)`](/documentation/Foundation/NSAttributedString/attributes(at:longestEffectiveRange:in:))

Returns the attributes for the character at the specified index and, by reference, the range where the attributes apply.

[`attribute(_:at:effectiveRange:)`](/documentation/Foundation/NSAttributedString/attribute(_:at:effectiveRange:))

Returns the value for an attribute with the specified name of the character at the specified index and, by reference, the range where the attribute applies.

[`attribute(_:at:longestEffectiveRange:in:)`](/documentation/Foundation/NSAttributedString/attribute(_:at:longestEffectiveRange:in:))

Returns the value for the attribute with the specified name of the character at the specified index and, by reference, the range where the attribute applies.

[`enumerateAttribute(_:in:options:using:)`](/documentation/Foundation/NSAttributedString/enumerateAttribute(_:in:options:using:))

Executes the specified closure or block for each range of a particular attribute in the attributed string.

[`enumerateAttributes(in:options:using:)`](/documentation/Foundation/NSAttributedString/enumerateAttributes(in:options:using:))

Executes the specified closure or block for each range of attributes in the attributed string.

[`NSAttributedString.EnumerationOptions`](/documentation/Foundation/NSAttributedString/EnumerationOptions)

Options for enumerating attributes.

### Getting text content attributes

[`NSAttributedString.Key`](/documentation/Foundation/NSAttributedString/Key)

The attributes you apply to ranges of characters in an attributed string.

[`NSAttributedString.TextHighlightStyle`](/documentation/Foundation/NSAttributedString/TextHighlightStyle)

Constants that specify the type of highlight to apply to text.

[`NSAttributedString.TextHighlightColorScheme`](/documentation/Foundation/NSAttributedString/TextHighlightColorScheme)

Constants that specify the highlight color to use with the text.

[`NSAttributedString.TextEffectStyle`](/documentation/Foundation/NSAttributedString/TextEffectStyle)

Constants for the type of effect to apply to the text.

[`NSAttributedString.SpellingState`](/documentation/Foundation/NSAttributedString/SpellingState)

Constants for the spelling state attribute key.

  <doc://com.apple.documentation/documentation/UIKit/NSUnderlineStyle>

  <doc://com.apple.documentation/documentation/UIKit/NSWritingDirectionFormatType>

### Getting text content attributes

[`NSAttributedString.Key`](/documentation/Foundation/NSAttributedString/Key)

The attributes you apply to ranges of characters in an attributed string.

  <doc://com.apple.documentation/documentation/UIKit/NSTextHighlightStyle>

  <doc://com.apple.documentation/documentation/UIKit/NSTextHighlightColorScheme>

  <doc://com.apple.documentation/documentation/UIKit/NSTextEffectStyle>

  <doc://com.apple.documentation/documentation/AppKit/NSSpellingState>

  <doc://com.apple.documentation/documentation/UIKit/NSUnderlineStyle>

  <doc://com.apple.documentation/documentation/UIKit/NSWritingDirectionFormatType>

### Getting document-wide attributes

[`NSAttributedString.DocumentAttributeKey`](/documentation/Foundation/NSAttributedString/DocumentAttributeKey)

The attributes you apply to an entire document.

[`NSAttributedString.DocumentReadingOptionKey`](/documentation/Foundation/NSAttributedString/DocumentReadingOptionKey)

Options for constructing an attributed string from data you read from disk.

[HTML attributes](/documentation/Foundation/html-attributes)

Documentwide attributes that provide control over the form of generated HTML.

[`NSAttributedString.DocumentType`](/documentation/Foundation/NSAttributedString/DocumentType)

Constants for the document type document attribute key.

[`NSAttributedString.TextLayoutSectionKey`](/documentation/Foundation/NSAttributedString/TextLayoutSectionKey)

Constants for the text layout sections document attribute key.

  <doc://com.apple.documentation/documentation/UIKit/NSTextScalingType>

### Getting document-wide attributes

  <doc://com.apple.documentation/documentation/UIKit/NSAttributedStringDocumentAttributeKey>

[Document reading option keys](/documentation/Foundation/document-reading-option-keys)

Keys for constructing an attributed string from data on disk.

[HTML attributes](/documentation/Foundation/html-attributes)

Documentwide attributes that provide control over the form of generated HTML.

  <doc://com.apple.documentation/documentation/UIKit/NSAttributedStringDocumentType>

  <doc://com.apple.documentation/documentation/UIKit/NSTextLayoutSectionKey>

  <doc://com.apple.documentation/documentation/UIKit/NSTextScalingType>

### Representing markdown attributes

[`InlinePresentationIntent`](/documentation/Foundation/InlinePresentationIntent)

A type that defines presentation intent for runs of characters for traits like emphasis, strikethrough, and code voice.

[`NSPresentationIntent`](/documentation/Foundation/NSPresentationIntent)

A type that contains the Markdown formatting for blocks of text, like paragraphs, lists, code blocks, and parts of tables.

[`NSAttributedStringMarkdownSourcePosition`](/documentation/Foundation/NSAttributedStringMarkdownSourcePosition)

The position of attributed string text in its original Markdown source string.

[`NSPresentationIntentKind`](/documentation/Foundation/NSPresentationIntentKind)

An enumeration of intended display styles for blocks of text like paragraphs, lists, and code blocks.

[`NSPresentationIntentTableColumnAlignment`](/documentation/Foundation/NSPresentationIntentTableColumnAlignment)

An enumeration of values for aligning the contents of table columns.

### Comparing strings

[`isEqual(to:)`](/documentation/Foundation/NSAttributedString/isEqual(to:))

Returns a Boolean value that indicates whether the attributed string is equal to the specified string.

### Getting the supported text-file formats

[`prefersRTFD(in:)`](/documentation/Foundation/NSAttributedString/prefersRTFD(in:))

Returns a Boolean value that indicates whether the specified range of text prefers RTFD formatting.

[`textTypes`](/documentation/Foundation/NSAttributedString/textTypes)

An array of UTI strings that identify the file types that attributed strings support, either directly or through a user-installed filter service.

[`textUnfilteredTypes`](/documentation/Foundation/NSAttributedString/textUnfilteredTypes)

An array of UTI strings that identify the file types that attributed strings support directly.

### Calculating linguistic units

[`doubleClick(at:)`](/documentation/Foundation/NSAttributedString/doubleClick(at:))

Returns the range of characters that form a word (or other linguistic unit) surrounding the specified index, taking language characteristics into account.

[`lineBreak(before:within:)`](/documentation/Foundation/NSAttributedString/lineBreak(before:within:))

Returns the appropriate line break when the character at the index doesn’t fit on the same line as the character at the beginning of the range.

[`lineBreakByHyphenating(before:within:)`](/documentation/Foundation/NSAttributedString/lineBreakByHyphenating(before:within:))

Returns the index of the closest character before the specified index, and within the specified range, that can fit on a new line by hyphenating.

[`nextWord(from:forward:)`](/documentation/Foundation/NSAttributedString/nextWord(from:forward:))

Returns the index of the first character of the word after or before the specified index.

### Performing automatic grammar agreement

[`inflecting()`](/documentation/Foundation/NSAttributedString/inflecting())

If the string has portions tagged with NSInflectionRuleAttributeName
that have no format specifiers, create a new string with those portions inflected
by following the rule in the attribute.

### Calculating ranges for common elements

[`itemNumber(in:at:)`](/documentation/Foundation/NSAttributedString/itemNumber(in:at:))

Returns the index of the item at the specified location within the list.

[`range(of:at:)`](/documentation/Foundation/NSAttributedString/range(of:at:)-1wrcp)

Returns the range of the individual text block that contains the specified location.

[`range(of:at:)`](/documentation/Foundation/NSAttributedString/range(of:at:)-6um0x)

Returns the range of the specified text list that contains the specified location.

[`range(of:at:)`](/documentation/Foundation/NSAttributedString/range(of:at:)-3fevu)

Returns the range of the specified text table that contains the specified location.

### Drawing the attributed string

[`draw(at:)`](/documentation/Foundation/NSAttributedString/draw(at:))

Draws the attributed string starting at the specified point in the current graphics context.

[`draw(in:)`](/documentation/Foundation/NSAttributedString/draw(in:))

Draws the attributed string inside the specified bounding rectangle in the current graphics context.

[`draw(with:options:context:)`](/documentation/Foundation/NSAttributedString/draw(with:options:context:))

Draws the attributed string in the specified bounding rectangle using the provided options.

### Getting metrics for the string

[`size()`](/documentation/Foundation/NSAttributedString/size())

Returns the size necessary to draw the string.

[`boundingRect(with:options:context:)`](/documentation/Foundation/NSAttributedString/boundingRect(with:options:context:))

Returns the bounding rectangle necessary to draw the string.

[`containsAttachments(in:)`](/documentation/Foundation/NSAttributedString/containsAttachments(in:))

Returns a Boolean value that indicates if the attributed string contains an attachment in the specified range.

### Deprecated

[Deprecated Symbols](/documentation/Foundation/deprecated-symbols)

Migrate your code away from using these symbols.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)