# LetterAvatarKit

![][Swift Version] ![][Pods] ![][Platform] ![][Codacy Badge]

`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:

![][screenshots]

## 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](https://cocoapods.org)

`LetterAvatarKit` is available through [CocoaPods](https://cocoapods.org). To install
it, simply add the following line to your Podfile:
```ruby
pod "LetterAvatarKit"
```

### Swift Package Manager

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

## Usage

### Swift

Using `LetterAvatarMaker`:

```swift
// 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:

```swift
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`:
```swift
let configuration = LetterAvatarBuilderConfiguration()
configuration.username = "Letter Avatar"
avatarImageView.image = UIImage.makeLetterAvatar(configuration: configuration)
```

Using UIImage extension:
```swift
avatarImageView.image = UIImage.makeLetterAvatar(username: "Letter Avatar")
```

## Customization

You can configure the following properties of `LetterAvatarBuilderConfiguration`:

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

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

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

```swift
/// 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
```

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

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

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

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

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

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

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

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

## Community

Questions, comments, issues, and pull requests are welcome!

## Contacts

- [GitHub](https://github.com/vpeschenkov)
- [Twitter](https://twitter.com/vpeschenkov)

## License

Distributed under the MIT license. See [LICENSE](https://github.com/vpeschenkov/LetterAvatarKit/blob/master/LICENSE) for more information.

[Screenshots]: https://i.imgur.com/n3SjH6q.jpg
[Platform]: https://cocoapod-badges.herokuapp.com/p/LetterAvatarKit/badge.png
[Pods]: https://cocoapod-badges.herokuapp.com/v/LetterAvatarKit/badge.png
[Swift Version]: https://img.shields.io/badge/swift-5.9-orange.svg?style=flat
[Codacy Badge]: https://api.codacy.com/project/badge/Grade/d0f9b1a4ccb64d4aacd18a971e4cf8b7