<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: 15.0.0 -",
    "macOS: 12.0.0 -",
    "tvOS: 15.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 8.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/AttributedString",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "s:10Foundation16AttributedStringV"
  },
  "title" : "AttributedString"
}
-->

# AttributedString

A value type for a string with associated attributes for portions of its text.

```
@dynamicMemberLookup struct AttributedString
```

## Overview

Attributed strings are character strings that have attributes for individual characters or ranges of characters. Attributes provide traits like visual styles for display, accessibility for guided access, and hyperlink data for linking between data sources. Attribute keys provide the name and value type of each attribute. System frameworks like Foundation and SwiftUI define common keys, and you can define your own in custom extensions.

### String Attributes

You can apply an attribute to an entire string, or to a range within the string. The string represents each range with consistent attributes as a *run*.

[`AttributedString`](/documentation/Foundation/AttributedString) uses subscripts and dynamic member lookup to simplify working with attributes from your call points. In its most verbose form, you set an attribute by creating an [`AttributeContainer`](/documentation/Foundation/AttributeContainer) and merging it into an existing attributed string, like this:

```swift
var attributedString = AttributedString("This is a string with empty attributes.")
var container = AttributeContainer()
container[AttributeScopes.AppKitAttributes.ForegroundColorAttribute.self] = .red
attributedString.mergeAttributes(container, mergePolicy: .keepNew)
```

Using the attributed string’s [`subscript(_:)`](/documentation/Foundation/AttributedStringProtocol/subscript(_:)-4thnp) method, you can omit the explicit use of an [`AttributeContainer`](/documentation/Foundation/AttributeContainer) and just set the attribute by its type:

```swift
attributedString[AttributeScopes.AppKitAttributes.ForegroundColorAttribute.self] = .yellow
```

Because an [`AttributedString`](/documentation/Foundation/AttributedString) supports dynamic member lookup — as described under [Attributes](https://docs.swift.org/swift-book/ReferenceManual/Attributes.html) in [The Swift Programming Language](https://docs.swift.org/swift-book/) — you can access its subscripts with dot syntax instead. When combined with properties like [`foregroundColor`](/documentation/Foundation/AttributeScopes/AppKitAttributes/foregroundColor) that return the attribute key type, this final form offers a natural way to set an attribute that applies to an entire string:

```swift
attributedString.foregroundColor = .green
```

This example works because AppKit defines an [`AttributeScope`](/documentation/Foundation/AttributeScope), [`AttributeScopes.AppKitAttributes`](/documentation/Foundation/AttributeScopes/AppKitAttributes), in which the property [`foregroundColor`](/documentation/Foundation/AttributeScopes/AppKitAttributes/foregroundColor) returns the type `AttributeScopes.AppKitAttributes.ForegroundColorAttribute`. Because AppKit’s attribute scope implements [`AttributeDynamicLookup`](/documentation/Foundation/AttributeDynamicLookup), the dot syntax resolves to an equivalent subscript expression, allowing `attributedString.foregroundColor` to replace `attributedString[AttributeScopes.AppKitAttributes.ForegroundColorAttribute.self]`.

You can also set an attribute to apply only to part of an attributed string, by applying the attribute to a range, as seen here:

```swift
var attributedString = AttributedString("The first month of your subscription is free.")
guard let range = attributedString.range(of: "free") else {return}
attributedString[range].foregroundColor = .green
```

You can access portions of the string with unique combinations of attributes by iterating over the string’s [`runs`](/documentation/Foundation/AttributedString/runs-swift.property) property.

You can define your own custom attributes by creating types that conform to [`AttributedStringKey`](/documentation/Foundation/AttributedStringKey), and collecting them in an [`AttributeScope`](/documentation/Foundation/AttributeScope). Custom keys should also extend [`AttributeDynamicLookup`](/documentation/Foundation/AttributeDynamicLookup), so callers can use dot-syntax to access the attribute.

### Creating Attributed Strings with Markdown

You can create an attributed string by passing a standard <doc://com.apple.documentation/documentation/Swift/String> or [`Data`](/documentation/Foundation/Data) instance that contains Markdown to initializers like [`init(markdown:options:baseURL:)`](/documentation/Foundation/AttributedString/init(markdown:options:baseURL:)-52n3u). The attributed string creates attributes by parsing the markup in the string.

```swift
do {
    let thankYouString = try AttributedString(
        markdown:"**Thank you!** Please visit our [website](https://example.com)")
} catch {
    print("Couldn't parse the string. \(error.localizedDescription)")
}
```

Localized strings that you load from strings files with initializers like [`init(localized:options:table:bundle:locale:comment:)`](/documentation/Foundation/AttributedString/init(localized:options:table:bundle:locale:comment:)-8dlnl) can also contain Markdown to add styling. In addition, these localized attributed string initializers can apply the [`replacementIndex`](/documentation/Foundation/AttributeScopes/FoundationAttributes/replacementIndex) attribute, which allows you to determine the range of replacement strings, whose order may vary between languages.

By declaring new attributes that conform to [`MarkdownDecodableAttributedStringKey`](/documentation/Foundation/MarkdownDecodableAttributedStringKey), you can add attributes that you invoke by using Apple’s Markdown extension syntax: `^[text](name:value, name:value, …)`. See the sample code project [Building a Localized Food-Ordering App](/documentation/Foundation/building-a-localized-food-ordering-app) for an example of creating custom attributes and using them with Markdown.

Localized attributed strings can also use the extension syntax to indicate parts of the string where the system can apply automatic grammar agreement. See the initializers that take a `localized:` parameter for examples of this extension syntax, as used with automatic grammar agreement.

### Attribute Scopes

The [`AttributedString`](/documentation/Foundation/AttributedString) API defines keys for common uses, such as text styling, semantically marking up formattable types like dates and numbers, and hyperlinking. You can find these in the [`AttributeScopes`](/documentation/Foundation/AttributeScopes) enumeration, which contains attributes for AppKit, Foundation, SwiftUI, and UIKit.

You can define your own attributes by implementing [`AttributedStringKey`](/documentation/Foundation/AttributedStringKey), and reference them by name by collecting them in an [`AttributeScope`](/documentation/Foundation/AttributeScope).

## Topics

### Creating an Attributed String

[`init()`](/documentation/Foundation/AttributedString/init())

Creates an empty attributed string.

[`init(_:)`](/documentation/Foundation/AttributedString/init(_:)-8tnoq)

Creates an attributed string from an attributed substring.

[`init(_:attributes:)`](/documentation/Foundation/AttributedString/init(_:attributes:)-2a45h)

Creates an attributed string from a string and an attribute container.

[`init(_:attributes:)`](/documentation/Foundation/AttributedString/init(_:attributes:)-8jqhp)

Creates an attributed string from a substring and an attribute container.

[`init(_:attributes:)`](/documentation/Foundation/AttributedString/init(_:attributes:)-8l0iq)

Creates an attributed string from a character sequence and an attribute container.

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

A container for attribute keys and values.

### Creating an Attributed String from Literal Values

[`init(stringLiteral:)`](/documentation/Foundation/AttributedString/init(stringLiteral:))

Creates an attributed string from the specified string literal, with no attributes.

### Creating a Localized Attributed String

[`init(localized:options:table:bundle:locale:comment:)`](/documentation/Foundation/AttributedString/init(localized:options:table:bundle:locale:comment:)-8dlnl)

Creates an attributed string by looking up a localized string from the app’s bundle.

[`init(localized:options:table:bundle:locale:comment:including:)`](/documentation/Foundation/AttributedString/init(localized:options:table:bundle:locale:comment:including:)-8uknv)

Creates an attributed string by looking up a localized string from the app’s bundle, including an attribute scope.

[`init(localized:options:table:bundle:locale:comment:including:)`](/documentation/Foundation/AttributedString/init(localized:options:table:bundle:locale:comment:including:)-5jzpg)

Creates an attributed string by looking up a localized string from the app’s bundle, including an attribute scope that a key path identifies.

  <doc://com.apple.documentation/documentation/Swift/String/LocalizationValue>

[`AttributedString.FormattingOptions`](/documentation/Foundation/AttributedString/FormattingOptions)

Options that affect the handling of attributes.

[`init(localized:)`](/documentation/Foundation/AttributedString/init(localized:))

Creates a localized attributed string from a localized string resource.

[`init(localized:including:)`](/documentation/Foundation/AttributedString/init(localized:including:)-2xebo)

Creates a localized attributed string from a localized string resource, including an attribute scope.

[`init(localized:including:)`](/documentation/Foundation/AttributedString/init(localized:including:)-15xc5)

Creates a localized attributed string from a localized string resource, including an attribute scope that a key path identifies.

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

A reference to a localizable string, accessible from another process.

### Creating a Localized Attributed String with a Default Value

[`init(localized:defaultValue:options:table:bundle:locale:comment:)`](/documentation/Foundation/AttributedString/init(localized:defaultValue:options:table:bundle:locale:comment:)-4n8e2)

Creates an attributed string by looking up a localized string from the app’s bundle, using a default value if necessary.

[`init(localized:defaultValue:options:table:bundle:locale:comment:including:)`](/documentation/Foundation/AttributedString/init(localized:defaultValue:options:table:bundle:locale:comment:including:)-2elmp)

Creates an attributed string by looking up a localized string from the app’s bundle, including an attribute scope, using a default value if necessary.

[`init(localized:defaultValue:options:table:bundle:locale:comment:including:)`](/documentation/Foundation/AttributedString/init(localized:defaultValue:options:table:bundle:locale:comment:including:)-9gjtg)

Creates an attributed string by looking up a localized string from the app’s bundle, including an attribute scope that a key path identifies, using a default value if necessary.

### Creating an Attributed String from Markdown

Use Markdown syntax to initialize an attributed string with text and attributes.

[Instantiating Attributed Strings with Markdown Syntax](/documentation/Foundation/instantiating-attributed-strings-with-markdown-syntax)

Use a Markdown-syntax string to iniitalize an attributed string with standard or custom attributes.

### Creating an Attributed String from a Reference Type

[`init(_:including:)`](/documentation/Foundation/AttributedString/init(_:including:)-9no47)

Creates a value-type attributed string from a reference type, including an attribute scope.

[`init(_:including:)`](/documentation/Foundation/AttributedString/init(_:including:)-puv0)

Creates a value-type attributed string from a reference type, including an attribute scope that a key path identifies.

[`init(_:)`](/documentation/Foundation/AttributedString/init(_:)-1fru0)

Creates a value-type attributed string from a reference type.

### Creating a Duplicate Attributed String

[`init(_:including:)`](/documentation/Foundation/AttributedString/init(_:including:)-6u3ho)

Creates an attributed string from another attributed string, including an attribute scope.

[`init(_:including:)`](/documentation/Foundation/AttributedString/init(_:including:)-9ejyj)

Creates an attributed string from another attributed string, including an attribute scope that a key path identifies.

### Applying and Modifying Attributes

[`setAttributes(_:)`](/documentation/Foundation/AttributedString/setAttributes(_:))

Sets the attributed string’s attributes to those in a specified attribute container.

[`mergeAttributes(_:mergePolicy:)`](/documentation/Foundation/AttributedString/mergeAttributes(_:mergePolicy:))

Merges the attributed string’s attributes with those in a specified attribute container.

[`AttributedString.AttributeMergePolicy`](/documentation/Foundation/AttributedString/AttributeMergePolicy)

An enumeration of behaviors to apply when merging attributes.

[`replaceAttributes(_:with:)`](/documentation/Foundation/AttributedString/replaceAttributes(_:with:))

Replaces occurrences of attributes in one attribute container with those in another attribute container.

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

A protocol that defines in-place mutations for attributes in an attributed string.

### Using Defined Attributes

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

Collections of attributes that system frameworks define.

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

A type to support dynamic member lookup of attributes and containers.

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

An attribute container that allows dynamic member lookup of its contents within the specified attribute scope.

### Searching for a Substring

### Accessing a Range

[`subscript(_:)`](/documentation/Foundation/AttributedString/subscript(_:)-2vqsz)

Returns a substring of the attributed string using a range to indicate the substring bounds.

### Accessing Indices

[Accessing Indicies Within an Attributed String](/documentation/Foundation/accessing-indicies-within-an-attributed-string)

Access a position within an attributed string, offset from the beginning, or before or after another known position.

### Accessing Views into the Attributed String

[`characters`](/documentation/Foundation/AttributedString/characters)

The characters of the attributed string, as a view into the underlying string.

[`AttributedString.CharacterView`](/documentation/Foundation/AttributedString/CharacterView)

A view into the underlying storage of the attributed string, as Unicode characters.

[`unicodeScalars`](/documentation/Foundation/AttributedString/unicodeScalars)

The Unicode scalars of the attributed string, as a view into the underlying string.

[`AttributedString.UnicodeScalarView`](/documentation/Foundation/AttributedString/UnicodeScalarView)

A view into the underlying storage of the attributed string, as Unicode scalars.

[`runs`](/documentation/Foundation/AttributedString/runs-swift.property)

The attributed runs of the attributed string, as a view into the underlying string.

[`AttributedString.Runs`](/documentation/Foundation/AttributedString/Runs-swift.struct)

An iterable view into segments of the attributed string, each of which indicates where a run of identical attributes begins or ends.

### Modifying an Attributed String

[`insert(_:at:)`](/documentation/Foundation/AttributedString/insert(_:at:))

Inserts the specified string at a specific index in the attributed string.

[`AttributedString.Index`](/documentation/Foundation/AttributedString/Index)

A type that represents the position of a character or code unit within an attributed string.

[`removeSubrange(_:)`](/documentation/Foundation/AttributedString/removeSubrange(_:))

Removes a range of characters from the attributed string.

[`replaceSubrange(_:with:)`](/documentation/Foundation/AttributedString/replaceSubrange(_:with:))

Replaces the contents in a range of the attributed string.

### Transforming Attributes

[`transformingAttributes(_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:)-9prm2)

Returns an attributed string by calling a closure that transforms one attribute of a source attributed string.

[`transformingAttributes(_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:)-64qnl)

Returns an attributed string by calling a closure that transforms one attribute, which a key path identifies, of a source attributed string.

[`transformingAttributes(_:_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:_:)-7kw1o)

Returns an attributed string by calling a closure that transforms two attributes of a source attributed string.

[`transformingAttributes(_:_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:_:)-8gt2n)

Returns an attributed string created by calling a closure that transforms two attributes, which key paths identify, of a source attributed string.

[`transformingAttributes(_:_:_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:_:_:)-4owv7)

Returns an attributed string by calling a closure that transforms three attributes of a source attributed string.

[`transformingAttributes(_:_:_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:_:_:)-5xmlf)

Returns an attributed string by calling a closure that transforms three attributes, which key paths identify, of a source attributed string.

[`transformingAttributes(_:_:_:_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:_:_:_:)-9uodg)

Returns an attributed string by calling a closure that transforms four attributes of a source attributed string.

[`transformingAttributes(_:_:_:_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:_:_:_:)-all0)

Returns an attributed string created by calling a closure that transforms four attributes, which key paths identify, of a source attributed string.

[`transformingAttributes(_:_:_:_:_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:_:_:_:_:)-3i7ac)

Returns an attributed string created by calling a closure that transforms five attributes of a source attributed string.

[`transformingAttributes(_:_:_:_:_:_:)`](/documentation/Foundation/AttributedString/transformingAttributes(_:_:_:_:_:_:)-9hppo)

Returns an attributed string created by calling a closure that transforms five attributes, which key paths identify, of a source attributed string.

[`AttributedString.SingleAttributeTransformer`](/documentation/Foundation/AttributedString/SingleAttributeTransformer)

A type that transforms an attribute by altering its range or value, or by replacing it entirely.

### Accessing Whole-String Attributes

[`subscript(dynamicMember:)`](/documentation/Foundation/AttributedString/subscript(dynamicMember:)-34zdf)

Returns an attribute value that a key path indicates.

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

A type to support dynamic member lookup of attributes and containers.

[`subscript(dynamicMember:)`](/documentation/Foundation/AttributedString/subscript(dynamicMember:)-9modq)

Returns a scoped attribute container that a key path indicates.

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

An attribute container that allows dynamic member lookup of its contents within the specified attribute scope.

### Combining Attributed Strings

[`append(_:)`](/documentation/Foundation/AttributedString/append(_:))

Appends a string to the attributed string.

[`+(_:_:)`](/documentation/Foundation/AttributedString/+(_:_:)-8sbsq)

Concatenates two attributed strings.

[`+(_:_:)`](/documentation/Foundation/AttributedString/+(_:_:)-drfc)

Concatenates two attributed strings or substrings.

[`+=(_:_:)`](/documentation/Foundation/AttributedString/+=(_:_:)-4dk88)

Appends an attributed string to another attributed string.

[`+=(_:_:)`](/documentation/Foundation/AttributedString/+=(_:_:)-6yimu)

Appends an attributed string or substring to another attributed string.

### Performing Automatic Grammar Agreement

[`inflected()`](/documentation/Foundation/AttributedString/inflected())

Applies automatic grammar agreement inflection rules to the attributed string and returns the result.

### Performing String Interpolation

[`AttributedString.InterpolationOptions`](/documentation/Foundation/AttributedString/InterpolationOptions)

Options that affect the behavior of string interpolation on the attributed string.

### Encoding and Decoding

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

A configuration type for encoding and decoding attributed strings.

[Encoding and Decoding Attributed String Keys](/documentation/Foundation/encoding-and-decoding-attributed-string-keys)

Protocols adopted by attribute keys to encode or decode data.

### Supporting types

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

A discontiguous portion of an attributed string.


---

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)