LetterAvatarKit

June 16, 2026 · View on GitHub

LetterAvatarKit provides an UIImage extension for generating letter-based avatars/placeholders. There are a few images showing what you can achive by using this framework:

Requirements

iOS 12+
tvOS 12+
Swift 5.9+

Features

Easy to use and intuitive interface
Highly flexible API allows for customization and integration into various projects
Use of the builder pattern for constructing avatar configurations
Support for creating circular, square, or bordered images
Wide range of flat UI colors available
Compatible with tvOS platform

Installation

CocoaPods

LetterAvatarKit is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "LetterAvatarKit"

Swift Package Manager

Add https://github.com/vpeschenkov/LetterAvatarKit as a package dependency in Xcode.

Usage

Swift

Using LetterAvatarMaker:

// Square avatar image
let avatarImage = LetterAvatarMaker()
    .setUsername("Letter Avatar")
    .build()
avatarImageView.image = avatarImage

// Circle avatar image with white border
let circleAvatarImage = LetterAvatarMaker()
    .setCircle(true)
    .setUsername("Letter Avatar")
    .setBorderWidth(1.0)
    .setBackgroundColors([ .red ])
    .build()
avatarImageView.image = circleAvatarImage

// Avatar image with explicit text instead of derived initials
let customTextAvatarImage = LetterAvatarMaker()
    .setUsername("+19")
    .setLetters("+19")
    .build()
avatarImageView.image = customTextAvatarImage

Using LetterAvatarMaker with closures:

let avatarImage = LetterAvatarMaker()
    .build { c in
        c.username = "Letter Avatar"
    }
avatarImageView.image = avatarImage

let avatarImage = LetterAvatarMaker()
    .build { c in
        c.circle = true
        c.username = "Letter Avatar"
        c.borderWidth = 1.0
        c.backgroundColors = [ .red ]
    }
avatarImageView.image = avatarImage

Using LetterAvatarBuilderConfiguration:

let configuration = LetterAvatarBuilderConfiguration()
configuration.username = "Letter Avatar"
avatarImageView.image = UIImage.makeLetterAvatar(configuration: configuration)

Using UIImage extension:

avatarImageView.image = UIImage.makeLetterAvatar(username: "Letter Avatar")

Customization

You can configure the following properties of LetterAvatarBuilderConfiguration:

/// The username.
open var username: String?

/// Letters that should be drawn instead of deriving them from the username.
open var letters: String?

/// The size of an avatar image.
open var size: CGSize = CGSize(width: 80, height: 80)

/// The flag that indicates of using single only one letter, otherwise,
/// as much as wil be possible to obtain. But no more than 3 letters.
open var useSingleLetter: Bool = false

/// The letters font.
open var lettersFont: UIFont?

/// The letters colors
open var lettersColor: UIColor = LKUIColorByRGB(red: 236, green: 240, blue: 241)

/// The background colors of an image.
open var backgroundColors: [UIColor] = UIColor.colors

/// The letters font attributes.
open var lettersFontAttributes: [NSAttributedString.Key: Any]?

/// Indicates whether to generate circle or square image.
open var circle: Bool = false

/// The border width of the image.
open var borderWidth: CGFloat = 0.0

/// The border color of the image.
open var borderColor: UIColor = UIColor.white

/// A Boolean flag indicating whether the avatar is opaque.
open var isOpaque: Bool = false