Image placeholders in pure CSS — or: Defying gods with math and color

Creating an LQIP in pure CSS using nothing but math, color and a bit of shenanigans

😎 Non-members: Read for free HERE!

Behold

… the absolute wickedness one can achieve with CSS. With just a single hex code…

… we can create this:

It may not look impressive, but that’s a 3-color “mesh gradient” image to act as an LQIP (Low Quality Image Placeholder).

A while back Lean Rada stunned the web development community with an ingenious trick: A CSS-only LQIP implementation. With a single value between -999,999 and 999,999 they create a blurry low-res representation of an image as a placeholder, entirely via CSS. I implore you to read their article to have your brain wrinkled because I cannot overstate how brilliant this is.

This inspired me to explore other avenues of implementing LQIPs, purely in CSS. Not to create something better (like hell I could), but to harness CSS’ power differently and see what else is possible.

Before we get into the technical nitty gritty, we first have to talk about LQIPs as a concept and the benefits of implementing LQIPs via CSS. If you’re already well up to speed or just don’t care, you can ⌘-F (or Ctrl-F) the 🧪 emoji to jump to the code and the science behind it all!

Don’t forget to check the implementation in action over here.

What the doggone flipping heck is an LQIP?

First of all, watch your language. Second, you’ve undoubtedly seen them before! You visit a site or open an app, but before the images are fully downloaded you are presented with an abstract representation in their place. This is called an LQIP: a Low Quality Image Placeholder. And they come in different forms. Like a single color (often the dominant color), a simple gradient of two colors, or perhaps a very blurry low-resolution version of the original image.

They’re a fancy feature that improve the UX ever so slightly: It prevents your site/app from looking barren when opening; they can help users potentially identify images early, but most importantly: they’re damn exquisite and show that you — the developer — care about the details. 😎

That said, they’re not as common as we probably think they are.

Implementing LQIPs requires some forethought on the backend side of things. Images have to be analysed, an LQIP has to be encoded into some form of “representation”, this “representation” then has to be stored somewhere for later use (e.g. a database). Finally, the frontend needs to receive these “representations” (preferably in the earliest payload) and generate the placeholder before downloading and showing the original image.

The second challenge is the fact an LQIP is more data you have to send to the frontend… And as a developer you want to avoid the point of diminishing returns: where the bandwidth (and time) of the extra data could’ve been better spent downloading the original files instead.

This is where the fight truly begins: finding an LQIP implementation that performs well and requires as little data as possible. Due to this extra hassle some developers opt to simply use Progressive JPEGs instead. Which isn’t a replacement for LQIPs entirely, but does present images to the user faster for an improved UX.

Different LQIP implementations

Perhaps the most common and naive way to implement LQIPs is by creating a low-res image of the original and have the frontend download it before downloading the original (or simultaneously).

Seems simple enough. But the drawback of this is the frontend will have to make more requests to the backend to download more files, which in turn is more data going back and forth.

Alternatively, the low-res image can be embedded inline into the HTML/CSS as a base64 string. Just search for “lqip” on npmjs.com to find countless packages doing exactly that for Vite and Webpack.

<img src="big.jpg" style="background:url('data:image/jpeg;base64,..')">

The drawback here, of course, is base64 makes files 33% larger. So… hmm, yes, less requests but bigger payloads. ¯\_(ツ)_/¯

Blurhash attempts to combat this. Rather than embedding a whole-ass image, a base83 string representation is created of a very very very low-res version instead. This string is then embedded into the HTML element as an attribute. Using JavaScript the base83 strings are read, decoded and an m×n mesh gradient image is generated.

<img src="img.jpg" data-lqip="B5JaQT0000{b~W0e">

The drawback here being… well, I’m saving that for the next section.

A final worthy mention is SQIP. Which uses SVG as LQIPs instead of tiny raster images. What’s interesting about SVG is it’s a very versatile format. It being vector based makes the graphic responsive and sharp at any resolution. Its filters feature allows you to add some seriously sick (realtime) effects too.

… but the SVGs you embed are still going to be hundreds of bytes large. Less — but still comparable — to base64 encoded JPEGs and WebPs.

Which brings us to…

The benefits of a pure CSS implementation

Going back to Blurhash, a bit of JavaScript is required on the frontend. However, let’s (mentally) go through the steps such JavaScript would have to go through.

First, all the elements in the DOM that are relevant need to be queried.

const images = document.querySelectorAll('img[data-lqip]')

For this to work proper you will most certainly have to wait for the DOM to finish parsing.

addEventListener('DOMContentLoaded', () => {
  parseLQIPs()
})

You then go through each element, read the hash, decode it and finally — somehow — render the LQIP. Blurhash does this by creating the gradients in a <canvas>, pixel by pixel.

It feels intuitive and gives you full control over the whole process, yes. But it’s also slow. You know what’s faster and more direct? CSS! Because:

CSS is blocking

It means the browser won’t render your page before your stylesheet(s) is fully loaded. Which is a good thing. It does so to prevent the dreadful Flash of Unstyled Content. The best part here is that the CSS solution works from the very first moment your page is visible. Even before the entire HTML is parsed!

CSS lets the browser do the rendering

As a frontend web developer you should know: nothing is faster than the browser itself. Something like CSS' linear-gradient() is going to outperform drawing a gradient onto a canvas via JavaScript. Better yet, the browser will also redraw the gradient whenever the element (or screen) changes size. Meaning our gradients will look ✨pristine✨ regardless of screen resolution or element size.

CSS is easier to implement (and less code)

Let’s say your website or webapp loads images dynamically. Applying the LQIP is literally a single line of code:

image.style.setProperty('--lqip', lqipValue)

Same thing if you’re using a framework like React. There’s no need for extra components et al to handle any extra logic. Just pop that CSS variable in there and Bob’s your uncle!

const style = {
  '--lqip': lqipValue
}

return <img src={src} style={style} />

Too easy.

With all that said you should now have a better understanding of LQIPs and the benefits of a pure CSS solution. Hopefully you’re as giddy as I am because it’s time for s c i e n c e !

🧪 The code and the science!

The goal was to make a minimalist LQIP implementation that supported at least two colors. The other goal was to have the data stored in a single CSS variable.

The first place to look, of course, is <integer>. Although undocumented, CSS integers have a safe range of -1,000,000 to 1,000,000. Which makes it almost a 20-bit value. Still, that’s plenty of space to store some data. The other benefit being the closer the value is to 0, the less bytes you need to write it.

--lqip:-1000000; /* 16 bytes */
--lqip:0; /* 9 bytes */

But we can do better. There’s a value type in CSS that has an even bigger range. And it’s one that’s been available since CSS variables became a thing: <color>. More specifically, its RGBA hex form: #RRGGBBAA.

RGBA are four 8-bit values put together, resulting in a single whopping 32-bit value. That’s a lot of bits to put data in. Initially the goal was to pack two colors… but greed prevailed and I decided to pack three colors instead. The first two colors being 11-bit, the last one being 10-bit.

This will limit the color precision, yes. Significantly so. With fewer bits we have lower ranges to work with. But this is the trade-off we can make. After all, the LQIP is going to be some blurry mess. Exact color precision is not of the utmost importance. Besides, the LQIP is only going to be shown temporarily until the original image is loaded in. Who’s gonna notice?

Let’s get cracking

First, we need the colors we are gonna cram into a single RGBA. There are several ways to do this, including the pretty complicated color quantization. But I decided to keep things simple: resize the image to a puny 3x3 resolution and grab the colors there.

I didn’t want a boring, linear gradient for the LQIP. Rather, it’d be nice if there was some shape and definition in there. So the LQIP will be built from a solid background color and two radial gradients placed on top, in a diagonal position. The colors will be grabbed from the top-left corner, the center and the bottom-right corner pixels of the 3x3 version.

Packing

Right, time to compress the ever loving ████ out of these ███ █████ █████ f████ing colors.

Packing the colors into a 11-bit and 10-bit integer is pretty straightforward if you’re familiar with bitwise operators.

type RGB = { r: number, g: number, b: number }

function packColor11bit(c: RGB): number {
  const r = Math.round((c.r / 0xFF) * 0b1111)
  const g = Math.round((c.g / 0xFF) * 0b1111)
  const b = Math.round((c.b / 0xFF) * 0b111)
  return (r << 7) | (g << 3) | b
}

function packColor10bit(c: RGB): number {
  const r = Math.round((c.r / 0xFF) * 0b111)
  const g = Math.round((c.g / 0xFF) * 0b1111)
  const b = Math.round((c.b / 0xFF) * 0b111)
  return (r << 7) | (g << 3) | b
}

With the colors packed we now combine them into a single integer and create the hex code.

const pc0 = packColor11bit(c0)
const pc1 = packColor11bit(c1)
const pc2 = packColor10bit(c2)
const combined = (BigInt(pc0) << 21n) | (BigInt(pc1) << 10n) | BigInt(pc2)
const hex = '#' + combined.toString(16).padStart(8, '0')

We put the hex code we created as a custom CSS variable in every element that requires a LQIP. Typically you’d put these only on <img> elements. But nothing is stopping you from putting them anywhere else, I guess.

<img src="image.jpg" style="--lqip:#abcdef01">

Unpacking

Now comes the fun part. Unpacking the colors from the single RGBA hex code in CSS.

CSS does not have any bitwise operators. But it does have math functions like round() and mod(). As luck would have it, that’s enough to “emulate” bitwise operations to snatch the bits from the RGBA hex.

But how do we get the bits from a specific color channel? There’s no function to just get, like, the red value from a color.

Or is there…?

Actually there is! And it’s (exclusively) possible in the relative color syntax.

--new-color: color(from var(--old-color) srgb r g b / alpha);
/* Alternatively */
--new-color: rgb(from var(--old-color) r g b / alpha);

The relative color syntax allows us to read and perform calculations on the individual channels of the color. Arbitrarily, even; you can swap the channels if you’d like! This is perfect. Because all we need to do is read from one color to create a new color.

The red of the first color are the first 4 bits of the red in the RGBA hex. This means we have to bit shift the value 4 bits to the right, then divide by 15 (the maximum 4-bit value (2⁴-1)). The calculation looks like this:

calc(round(down, r * 255 / pow(2,4)) / 15)

For green we need the last 4 bits of the red channel in the RGBA hex. Here we use mod() to emulate a bitwise AND:

calc(mod(round(down, r * 255), pow(2,4)) / 15) 

With the basic maths explained, here’s the full CSS code to unpack three colors from a single RGBA hex code:

--lqip-c0: color(
  from var(--lqip)
  srgb
  calc(round(down, r * 255 / pow(2,4)) / 15)
  calc(mod(round(down, r * 255), pow(2,4)) / 15)
  calc(round(down, g * 255 / pow(2,5)) / 7)
  / 100%
);

--lqip-c1: color(
  from var(--lqip)
  srgb
  calc(mod(round(down, g * 255 / 2), pow(2,4)) / 15)
  calc(((mod(round(down, g * 255), 2) * pow(2,3)) + (round(down, b * 255 / pow(2,5)))) / 15)
  calc(mod(round(down, b * 255 / pow(2,2)), pow(2,3)) / 7)
  / 100%
);

--lqip-c2: color(
  from var(--lqip)
  srgb
  calc((((mod(round(down, b * 255), pow(2,2)) * 2)) + round(down, alpha * 255 / pow(2,7))) / 7)
  calc(mod(round(down, alpha * 255 / pow(2,3)), pow(2,4)) / 15)
  calc(mod(round(down, alpha * 255), pow(2,3)) / 7)
  / 100%
);

Hooo boy. 😑 With that out of the way we can finally construct our LQIP.

Lean figured out a radial gradient can look more attractive by using an eased interpolation, rather than a linear one. (I’m paraphrasing here) So for our gradients we’ll do just that: set the steps at every 10% to simulate the easing. The background property — and the final piece of the puzzle — looks like this:

background:
  radial-gradient(
    150% 75% at 80% 100%,
    var(--lqip-c2),
    rgb(from var(--lqip-c2) r g b / 98%) 10%,
    rgb(from var(--lqip-c2) r g b / 92%) 20%,
    rgb(from var(--lqip-c2) r g b / 82%) 30%,
    rgb(from var(--lqip-c2) r g b / 68%) 40%,
    rgb(from var(--lqip-c2) r g b / 32%) 60%,
    rgb(from var(--lqip-c2) r g b / 18%) 70%,
    rgb(from var(--lqip-c2) r g b / 8%) 80%,
    rgb(from var(--lqip-c2) r g b / 2%) 90%,
    transparent
  ),
  radial-gradient(
    100% 75% at 40% 50%,
    var(--lqip-c1),
    rgb(from var(--lqip-c1) r g b / 98%) 10%,
    rgb(from var(--lqip-c1) r g b / 92%) 20%,
    rgb(from var(--lqip-c1) r g b / 82%) 30%,
    rgb(from var(--lqip-c1) r g b / 68%) 40%,
    rgb(from var(--lqip-c1) r g b / 32%) 60%,
    rgb(from var(--lqip-c1) r g b / 18%) 70%,
    rgb(from var(--lqip-c1) r g b / 8%) 80%,
    rgb(from var(--lqip-c1) r g b / 2%) 90%,
    transparent
  ),
  var(--lqip-c0);

🏁 Done!

And there you have it. With very little code and very easy math we have:

• A representation of an LQIP that is incredibly minimal and requires but a few bytes to be sent to the frontend. The frontend implementation is also minuscule. A huge bandwidth saver.
• An LQIP that performs well and is responsive thanks to letting the browser do the heavy lifting.
• An implementation that can be applied beyond just websites and webapps (refer to Appendix B for an example).
• Defied the gods and harnessed a new unthinkable power in CSS.

Don’t forget, you can see the LQIP in action here, as well try out your own images.

What now?

Like most things in life, it’s not perfekt; there’s still room for improvement.

For instance: near gray colors may turn more saturated and become more colorful due to the lack of precision. One could better analyze the colors picked out of the 3x3 image before packing them into the RGBA. (Or use a different method altogether.)

Another idea is to add a second CSS variable for three more colors to create a six color mesh gradient:

<img src="image.jpg" style="--lqip0:#49bc6c88; --lqip1:#8ace6d80">

Thank you very much for reading. Hopefully this article inspired you just as much as Lean’s article inspired me. It feels like there’s still a huge world of CSS potential left to discover. And it always excites me when people come up with new mind-boggling, ingenious, Einstein-levels of brilliance tricks. Please share them with the world!

• The repository can be found on GitHub.
• This article is also posted on DEV.to.

Thanks again! 🤗

Appendix A: Embedded as attribute

In the (near?) future we should be able to utilise attr(), allowing us to put the hex code as a separate attribute and read it as a color in CSS. This would make placing the hex code in the element easier for the backend; no longer having to jam the code awkwardly in a style="".

<img src="image.jpg" data-lqip="#abcdef01">

[data-lqip] {
  --lqip: attr(data-lqip type(<color>), white);
  /* ... */
}

Appendix B: Native app implementation

Being a Swift developer as well I figured it’s worth showing how easy it is to code this LQIP implementation in a SwiftUI app. Just to prove the technique is not necessarily web (CSS) exclusive.

The Swift code can be found in the GitHub Gist.

Read for free here!

⚠ ️This article will become redundant once all browsers support the CSS Color Module 5 relative color syntax.

color-mix() is creeping into browsers! It's now available in Safari, Chrome (partially (see bottom)) and should ship in Firefox soon (currently behind a config flag).

This article assumes you’re already aware of color-mix()'s existence. If this is the first time you're reading about it, I highly recommend you read Chrome Developer's blogpost about this amazing new CSS function first.

Just like nesting, CSS is slowly growing stronger by adopting features we normally would need preprocessors for (like Less and Sass). Another one of those features — which this article is all about — is color manipulation.

Changing the alpha value (opacity)

In both Less and Sass we can use variables to create the same color but with a different alpha value.

$color-primary: rgb(255 125 0);
color: rgb($color-primary, 0.5);

The alpha value can even be overridden if it was specifically declared in the variable.

$color-highlight: rgb(255 125 0 / 0.5); // Alpha of 0.5
background-color: rgb($color-highlight, 0.9); // Overridden to have an alpha of 0.9

Now this isn’t really anything special. We can already achieve something similar with pure CSS. That is, if we were to declare the RGB values in a separate variable we can use said variable in rgb():

--color-primary-rgb: 255 125 0;
--color-primary: rgb(var(--color-primary-rgb));

background-color: rgb(var(--color-primary-rgb) / 0.75);
color: var(--color-primary);

Of course, if we were to do this for every possible color, we’d end up with a hell of a lot variables.

Luckily we can also adjust the alpha value with color-mix()! The magic trick is using transparent:

--color-primary: rgb(255 125 0);
color: color-mix(in srgb, transparent, var(--color-primary) 75%); /* rgb(255 125 0 / 0.75)

By mixing a color with transparent we get the same color back but with a different alpha value. Because the 75% is grouped with the CSS variable it means the resulting color uses 75% of the color on the right, which has an alpha value of 1.0. Thus the resulting color would be the same as rgb(255 125 0 / 0.75). If the 75% was grouped with transparent then the resulting color would instead be rgb(255 125 0 / 0.25). It doesn’t matter whether transparent is used left or right. The important part is where you place the percentage.

Omitting the percentage entirely would result in a color with alpha value 0.5.

darken() and lighten()

Both Less and Sass supply a bunch of useful color functions. Two of those are darken() and lighten(). As their name already tells you these functions return a darker and a lighter variant of a given color, based on a give percentage. These are useful to create, for example, colors for hover or various states.

@color-primary: rgb(255 125 0);
background-color: darken(@color-primary, 20%); // A '20%' darker color.

But thanks to color-mix() we can now get the same effect using pure CSS! The trick? Use either black or white to darken or lighten the color respectively:

--color-primary: rgb(255 125 0);
background-color: color-mix(in srgb, black 20%, var(--color-primary)); /* Darken by 20% */
background-color: color-mix(in srgb, white 20%, var(--color-primary)); /* Lighten by 20% */

Now there are two things to keep in mind:

• The percentage you use in the Less/Sass functions does not match what you’d use in color-mix().
• Depending on the colorspace you will get different results.

In this Codepen we can compare and test colors between the available colorspaces as well as Sass’ darken() function.

The first two columns show Sass’ darken() function. All columns demonstrate a range from 10% to 90%, with the exception of the second column: which uses 5% to 50%. This is because both darken() and lighten() are pretty 'sensitive'.

It looks like using srgb (third column) and doubling the value you'd normally use in Sass gives similar results.

Testing with blue supports this theory:

However, once we try green the theory clearly fails:

So keep this in mind: switching from Less or Sass’ darken() and lighten() to color-mix() isn't a simple one-to-one translation. You're gonna have to carefully test each color to make sure you either get the same - or at least similar - result.

For completion sake, here’s comparing Sass’ lighten() with using white in color-mix():

Conclusion

So, that’s another usecase where we can use pure CSS instead of Less or Sass. Does this mean Less and Sass are becoming obsolete? Heavens no. They’re preprocessors! And preprocessors will always have a role in build pipelines. Especially for bigger projects. They help us prevent shipping certain code to production. They provide us with useful utilities to either automate or write less code (e.g. loops and mixins). They’ll be with us for a long time.

That said, both Less and Sass’ role ends after compiling the CSS. They can’t help us much during runtime. Which is exactly where features like CSS variables, calc(), color-mix(), et al. show their strength. And thus should take precedence over Less/Sass solutions.

Known bugs

As of writing this there’s a bug in Chrome (v112) where using color-mix() with CSS variables only works for color and background-color. Anything else (box-shadow, border-color, etc...) seems to give undefined behavior. Resulting in either black or the color defined in the CSS variable remaining untouched. Firefox and Safari seem fine, however.

Edit: This issue has been fixed and should arrive in either Chrome 114 or 115!

Thanks for reading!

The delegation pattern can be found everywhere in Apple’s frameworks. You’ve most likely used it countless times if you’ve developed iOS or macOS apps. Let’s go over it real quick for the sake of this article.

You have an object (the sender) that references another object (the delegate):

class AudioPlayer {
    weak var delegate: AudioPlayerDelegate?
}

You have a protocol for said delegate:

protocol AudioPlayerDelegate: AnyObject {
    func audioPlayerConnected(_ audioPlayer: AudioPlayer)
    func audioPlayer(_ audioPlayer: AudioPlayer, changedSong song: Song)
    // Etc...
}

And at some point the sender object interacts with the delegate. For example to inform a certain event has occurred:

delegate?.audioPlayerConnected(self)

This is all easy to understand and it has served us well for decades.

Now let’s look at a different implementation to achieve something similar.

In 2019 Apple introduced Combine. A powerful framework that allows for reactive programming with a stream-like interface. One particularly interesting object in Combine we’ll be focusing on is PassthroughSubject. It's a publisher that simply passes through a value to its subscribers when you send it one. That's it. And as it turns out it makes for a great way to define events!

Here’s what it could look like:

class AudioPlayer {
    let onConnected = PassthroughSubject<Void, Never>
    let onSongChanged = PassthroughSubject<Song, Never>
}

The sender object no longer contains a weak var delegate property. Nor is there a delegate protocol. Rather, the object exposes its events as PassthroughSubject publishers. Each defined with the type of value it passes through (using Void if there is no value), and has Never for Failure: meaning the publisher will never send an error. This makes subscribing to the publisher a whole lot easier.

Objects can subscribe to these events wherever and whenever they wish, just like you would with any other Combine publisher:

private var cancellables = Set<AnyCancellable>()

audioPlayer
    .onSongChanged
    .sink { song in
        print("Current song is", song.title)
    }
    .assign(to: &cancellables)

When the event in question occurred the object can inform all the subscribers using send():

onSongChanged.send(newSong)

Use a tuple to send multiple values at once:
let onUserRequest = PassthroughSubject<(User, Song), Never>()

That’s the gist of it. It’s clearly a different way of thinking and programming, and if you’re unfamiliar with this pattern it may take a second to fully wrap your head around it.

Notice how the names of these PassthroughSubjects start with 'on'. This is to better differentiate the events from all other properties of the object. A clear indication this is an 'event'.

Needless to say, let’s go through the ups and downs of using this pattern.

Unlimited subscribers

With the delegation pattern you tend to have only one of them:

weak var delegate: AudioPlayerDelegate?

But this can be pretty limiting. Now only one object has the privilege of listening to events.

To combat this developers have either resorted to NotificationCenter (which is both cumbersome and not type safe!) or have come with their own custom solution:

public var listeners = Set<WeakValue<AudioPlayerDelegate>>()

// Adding a listener:
audioPlayer.listeners.insert(WeakValue(self))

// `AudioPlayer` informing all listeners:
listeners.forEach { $0.value?.audioPlayerConnected(self) }

Which is cute and all, but rather unstandardized and unfamiliar to anyone but themself.

Combine brings Swift users a well documented and, dare we say, standardized way of writing reactive code. No need to reinvent the wheel.

Subscribe only to what you care about

Delegates work with protocols:

protocol AudioPlayerDelegate: AnyObject {
    func audioPlayerConnected(_ audioPlayer: AudioPlayer)
    func audioPlayerDisconnected(_ audioPlayer: AudioPlayer)
    func audioPlayer(_ audioPlayer: AudioPlayer, changedSong song: Song)
    func audioPlayer(_ audioPlayer: AudioPlayer, changedQuality quality: Quality)
    // Etc...
}

The protocol defines the interface — i.e. the required methods and properties — of an object. However, sometimes we don’t care about all the events. We just want to listen to one event. And… well you can see where this is going. This could mean you’ll have objects containing empty methods or properties when conforming to a protocol:

class NowPlayingUI: AudioPlayerDelegate {
    func audioPlayer(_ audioPlayer: AudioPlayer, changedSong song: Song) {
        albumArt.image = UIImage(contentsOf: song.albumArt.path)
        titleLabel.text = song.title
    }

    // We don't care about these. But Swift demands we include them.
    func audioPlayerConnected(_ audioPlayer: AudioPlayer) {}
    func audioPlayerDisconnected(_ audioPlayer: AudioPlayer) {}
    func audioPlayer(_ audioPlayer: AudioPlayer, changedQuality quality: Quality) {}
}

One horrible way to circumvent this is to use the disgusting @obj optional keywords. But as Swift grows we should rely less on these nasty ugly legacy Objective-C features.

With Combine other objects are able to subscribe only to whatever event they care about.

With that all said and done let’s look at some of the challenges when using PassthroughSubjects for events...

Always having to use [weak self]

Every time you use .sink on a publisher, and you reference self in any way, you're almost always forced to use [weak self].

audioPlayer
    .onSongChanged
    .sink { [weak self] song in
        self?.songTitle = song.title
        self?.songDuration = Double(song.duration) / 1000
    }
    .store(in: &cancellables)

Okay — so you’re not forced per se, but it is safer. This is of course to prevent circular references and to prevent keeping objects in memory beyond their lifespan. Using [weak self] can be tedious as you then have to work with an optional self. However, if you're feeling courageous you can use [unowned self]! (But seriously though, don't...)

One-way communication

The original delegation pattern allows for two-way communication between the sender and the delegate, if so desired. This allows the sender to ask the delegate to return or modify a value. Or to tell the sender how to respond to a certain event.

// Asking the delegate for a value.
quality = delegate?.audioPlayerPreferredQuality(self) ?? .auto

// Asking the delegate whether it's okay to proceed.
guard delegate?.audioPlayer(self, allowStream: url) != false else {
    return
}

Two-way communication is not Combine’s intended purpose!

Apple-bound (-ish)

Combine is a framework developed by Apple for Apple platforms. It’s closed source and only works on iOS (iPadOS), macOS, tvOS and watchOS. Which means using Combine can be a bit of a challenge if you were using Swift for Linux or Windows projects.

Luckily there are open source alternatives — like CombineX and OpenCombine — that strive to become a perfect replica of Apple’s Combine framework. Except open source and not bound to Apple platforms.

Conclusion

Combine is an extremely powerful and convenient framework. It playing a prominent role in SwiftUI means a lot of developers will become familiarized with it (many already have). Meaning there’s no need to reinvent the wheel yourself. Using PassthroughSubject for events will allow you (and perhaps other developers) to further harnass the power of Combine.

Nonetheless, as shown above, it is not necessarily a full replacement for the delegation pattern. It’s important to fully understand the flow of your code before deciding to go with PassthroughSubjects (that is, if this article has you convinced!).

For me personally however, I can say I’ve written far less delegate and NotificationCenter code since the introduction of Combine. 😉

Thanks for reading!

Extra

If PassthroughSubject<T, Never> is too much of a mouthful for you then consider using a typealias to make things slightly more convenient:

typealias Event<T> = PassthroughSubject<T, Never>

let onStart = Event<Void>()
let onSongChanged = Event<Song>()

Creating a very primitive chat app in SwiftUI, while using Swift and WebSockets to create the chat server. It’s Swift from top to bottom, honey!

This tutorial is also available in Markdown, together with the final code, on Github.

Introduction

In this tutorial we’ll make a rather primitive, but functional chat app. The app will run on iOS or macOS — or both! The beauty of SwiftUI is how little effort it takes to make a multiplatform app.

Of course, a chat app will have very little use without a server to talk to. Hence we’ll be making a very primitive chat server as well, utilizing WebSockets. Everything will be built in Swift and run locally on your machine.

This tutorial assumes you already have a bit of experience developing iOS/macOS apps using SwiftUI. Although concepts will be explained as we go, not everything will be covered in depth. Needless to say, if you type along and follow the steps, by the end of this tutorial you’ll have a working chat app (for iOS and/or macOS), that communicates with a server that you also made! You will also have a basic understanding of concepts like server-side Swift and WebSockets.

If none of that interests you, you can always just download the final code from Github.

Quick summary of what’s to come

In short, we will start by making a very simple, plain, featureless server. We’ll build the server as a Swift Package, then add the Vapor web framework as a dependency. This will help us setup a WebSocket server with just a few lines of code.

Afterwards we will start building the frontend chat app. Quickly starting with the basics, then adding features (and necessities) one by one.

Most of our time will be spent working on the app, but we’ll be going back and forth between the server code and the app code as we add new features.

Requirements

• macOS 10.15+
• Xcode 12 beta 5+

Optional

• macOS 11 beta
  (if you want to run the app on macOS)
• iPhone/iPad running iOS 14 beta 5+
  (if you want to run the app on a physical device)

Let’s begin!

Creating the server

Open Xcode 12 and start a new project (File > New Project). Under Multiplatform select Swift Package.

Call the Package something logical — something self explanatory — like “ChatServer”. Then save it wherever you like.

Swift Package?

When creating a framework or multiplatform software (e.g. for macOS and Linux) in Swift, Swift Packages are the preferred way to go. They’re the official solution for creating modular code that other Swift projects can easily use. A Swift Package doesn’t necessarily have to be a modular project though: it can also be a stand-alone executable that simply uses other Swift Packages as dependencies (which is what we’re doing).

It may have occurred to you that there’s no Xcode project (.xcodeproj) present for the Swift Package. To open a Swift Package in Xcode like any other project, simply open the Package.swift file. Xcode should recognize you're opening a Swift Package and opens the entire project structure. It will automatically fetch all the dependencies at the start.

You can read more about Swift Packages and Swift Package Manager on the official Swift website.

Setup Package.swift

To handle all the heavy lifting of setting up a server, we’ll be using the Vapor web framework. Vapor comes with all the necessary features to create a WebSocket server.

WebSockets?

To provide the web with the ability to communicate with a server in realtime, WebSockets were created. It’s a well described spec for safe realtime (low-bandwidth) communication between a client and a server. E.g.: multiplayer games and chat apps. Those addictive in-browser multiplayer games you’ve been playing on valuable company time? Yup, WebSockets!

However, if you wish to do something like realtime video streaming you’re best looking for a different solution. 🙂

Though we’re making an iOS/macOS chat app in this tutorial, the server we’re making can just as easily talk to other platforms with WebSockets. Indeed: if you want you could also make an Android and web version of this chat app, talking to the same server and allowing for communication between all platforms!

Vapor?

The internet is a complex series of tubes. Even responding to a simple HTTP request requires some serious amount of code. Luckily, experts in the field have developed open source web frameworks that do all the hard work for us for decades now, in various programming languages. Vapor is one of them, and it’s written in Swift. It already comes with some WebSocket capabilities and it’s exactly what we need.

Vapor isn’t the only Swift powered web framework though. Kitura and Perfect are also well known frameworks. Though Vapor is arguably more active in its development.

Xcode should open the Package.swift file by default. This is where we put general information and requirements of our Swift Package.

Before we do that though, look in the Sources/ChatServer folder. It should have a ChatServer.swift file. We need to rename this to main.swift. Once that's done, return to Package.swift.

Under products:, remove the following value:

.library(name: "ChatServer", targets: ["ChatServer"])

… and replace it with:

.executable(name: "ChatServer", targets: ["ChatServer"])

After all, our server isn’t a Library. But a stand-alone executable, rather. We should also define the platforms (and minimum version) we expect our server to run on. This can be done by adding platforms: [.macOS(v10_15)] under name: "ChatServer":

name: "ChatServer",
	platforms: [
		.macOS(.v10_15),
	],

All this should make our Swift Package ‘runnable’ in Xcode.

Alright, let’s add Vapor as a dependency. In dependencies: [] (which should have some commented-out stuff), add the following:

.package(url: "https://github.com/vapor/vapor.git", from: "4.0.0")

When saving the Package.swift file, Xcode should start automatically fetching the Vapor dependencies with verison 4.0.0 or newer. As well as all its dependencies.

We just have to make one more adjustment to the file while Xcode is doing its thing: adding the dependency to our target. In targets: you will find a .target(name: "ChatServer", dependencies: []). In that empty array, add the following:

.product(name: "Vapor", package: "vapor")

That’s it. Our Package.swift is done. We've described our Swift Package by telling it:

• It’s an executable, not a library
• To import the Vapor web framework dependency (and all its dependencies)
• Link the Vapor dependency to our executable, making it accessible in our code

The final Package.swift should look like this(-ish):

Now, it’s finally time for…

Writing some actual code

In Xcode, open Sources/ChatServer/main.swift and delete everything in there. It's worthless to us. Instead, make main.swift look like this:

import Vapor

var env = try Environment.detect() // 1
let app = Application(env) // 2

defer { // 3
	app.shutdown()
}

app.webSocket("chat") { req, client in // 4
	print("Connected:", client)
}

try app.run() // 5

💥 Bam! That’s all it takes to start a (WebSocket) server using Vapor. Look at how effortless that was.

1. First we make a default Environment configuration.
2. We initialize a Vapor Application instance and pass it the Environment.
3. Register a defer and call .shutdown() which will perform any cleanup when exiting the program.
4. Start listening to any incoming WebSocket connections on /chat.
5. Acually start the Vapor Application instance.

Now ▶️ run the program in Xcode and grab something to drink. Building the first time takes a while as Xcode will need to build all those Vapor dependencies first. (But only once)

Once the program has successfully run, you may not see anything resembling an app. That’s because server software don’t tend to have graphical user interfaces. But rest assured, the program is alive and well in the background, spinning its wheels. The Xcode console should show the following message, however:

notice codes.vapor.application : Server starting on http://127.0.0.1:8080

This means the server can successfully listen to incoming requests. This is great, because we now have a WebSocket server we can start connecting to!

I don’t believe you?

If for whatever reason you think I’ve been spewing nothing but heinous lies this whole time, you can test the server yourself!

Open up your favourite browser and make sure you’re in an empty tab. (If it’s Safari, you will need to enable Developer mode first.) Open the Inspector (Cmd+Option+I) and go to the Console. Type in

new WebSocket('ws://localhost:8080/chat')

and hit Return. Now take a look at the Xcode console. If all went well, it should now show Connected: WebSocketKit.WebSocket.

⚠️ Important ⚠️

The server is only accessible from your local machine. This means you cannot connect your physical iPhone/iPad to the server. Instead, we’ll be using the Simulator in the following steps to test our chat app.

To test the chat app on a physical device, some (small) extra steps need to be taken. Refer to Appendix A for more details.

Creating the app

Though we’re not done with the backend yet, it’s time to move to the frontend. The chat app itself!

In Xcode create a new project. This time, under Multiplatform select App. Again, choose a beautiful name for your app and continue. (I chose SwiftChat. I agree, it’s perfect 🌈)

The app does not rely on any external third-party frameworks or libraries. Indeed, everything we need is available via Foundation, Combine and SwiftUI (in Xcode 12+).

Let’s start working on the chat screen immediately. Create a new Swift file and name it ChatScreen.swift. It doesn't matter whether you choose the Swift File or the SwiftUI View template. We're deleting everything in it regardless.

Here’s the starter’s kit of ChatScreen.swift:

In ContentsView.swift, replace the Hello World with ChatScreen():

struct ContentView: View {
	var body: some View {
		ChatScreen()
	}
}

What we have here:

1. A ScrollView where we will place all our messages in.
2. The message box where the user can type in their message.
3. A submit button to send the message (though later on users will also be able to submit by pressing Return).
4. Disabling the submit button if the message is empty.

If you wish to make different design choices, go right ahead. 🙂

Connecting to the server

Now let’s start working on some non-UI related logic: connecting to the very server we just made.

SwiftUI, together with the Combine framework, provides developers with tools to implement Seperation of Concerns effortlessly in their code. Using the ObservableObject protocol and @StateObject (or @ObservedObject) property wrappers we can implement non-UI logic (referred to as Business Logic) in a separate place. As things should be! After all, the only thing the UI should care about is displaying data to the user and reacting to user input. It shouldn't care where the data comes from, or how it's manipulated.

Coming from a React background, this luxury is something I’m incredibly envious of.

There are thousands upon thousands articles and discussions about software architecture. You’ve probably heard or read about concepts like MVC, MVVM, VAPOR, Clean Architecture and more. They all have their arguments and their applications.

Discussing these is out-of-scope for this tutorial. But it’s generally agreed upon that business logic and UI logic should not be intertwined.

This concept is true just as much for our ChatScreen. The only thing the ChatScreen should care about is displaying the messages and handling the user-input text. It doesn’t care about ✌️WeBsOcKeTs✌, nor should it.

You can create a new Swift file or write the following code at the bottom of ChatScreen.swift. Your choice. Wherever it lives, make sure you don't forget the imports!

This may be a lot to take in, so let’s slowly go through it:

1. We store a URLSessionWebSocketTask in a property.
   URLSessionWebSocketTask objects are responsible for WebSocket connections. They're residents of the URLSession family in the Foundation framework.
2. Public method to start the connection.
3. URL to our server.
   Remember: the server runs locally on your machine (which means we use the IP 127.0.0.1 or localhost). The default port of Vapor applications is 8080. And we put a listener to WebSocket connections in the /chat path.
4. We create a URLSessionWebSocketTask and store it in the instance's propety.
5. We bind an ‘on message’ handler.
   Whenever a message is received from the server, the method onReceive(incoming:) will be called. More on this later.
6. Start the WebSocket connection.
7. A public method to close the connection (very important!).
8. Disconnecting the WebSocket connection.
   With WebSockets, you have the option to inform the server why a client disconnected. With optional additional data provided.
9. Make sure we gracefully disconnect when the ChatScreenModel is purged from memory.

This is a great start. We now have a place where we can put all our WebSocket logic without cluttering the UI code. It’s time to have ChatScreen communicate with ChatScreenModel.

Add the ChatScreenModel as a State Object in ChatScreen:

struct ChatScreen: View {
	@StateObject private var model = ChatScreenModel() // <this
	@State private var message = ""
	
	// etc...
}

When should we connect to the server? Well, when the screen is actually visible, of course. You may be tempted to call .connect() in the init() of ChatScreen. This is a dangerous thing. In fact, in SwiftUI one should try to avoid putting anything the init(), as the View can be initialized even when it will never appear. (For instance in LazyVStack or in NavigationLink(destination:).) It'd be a shame to waste precious CPU cycles. Therefore, let's defer everything to onAppear.

Add an onAppear method to ChatScreen. Then add and pass that method to the .onAppear(perform:) modifier of VStack:

struct ChatScreen: View {
	// ...

	private func onAppear() {
		model.connect()
	}

	var body: some View {
		VStack {
			// ...
		}
		.onAppear(perform: onAppear)
	}
}

Wasted space?

Plenty of people prefer to write the contents of these methods inline instead:

.onAppear { model.connect() }

This is nothing but a personal preference. Personally I like to define these methods separately. Yes, it costs more space. But they’re easier to find, are reusable, prevent the body from getting (more) cluttered and are arguably easier to fold. 🙂

By the same token, we should also disconnect when the view disappears. The implementation should be self explanatory, but just in case:

struct ChatScreen: View {
	// ...

	private func onDisappear() {
		model.disconnect()
	}

	var body: some View {
		VStack {
			// ...
		}
		.onAppear(perform: onAppear)
		.onDisappear(perform: onDisappear)
	}
}

It’s very important to close WebSocket connections whenever we stop caring about them. When you (gracefully) close a WebSocket connection, the server will be informed and can purge the connection from memory. The server should never have dead or unknown connections lingering in memory.

Phew. Quite a ride we’ve been through so far. Time to test it out. ▶️ Run the app! (Use Simulator if you’re testing for iOS.) Make sure you still have the server running in your other Xcode window. When the app has successfully started and is displaying ChatScreen, you should see the Connected: WebSocketKit.WebSocket message in the Xcode console of the server. If not, retrace your steps and start debugging!

Testing disconnection

One more thing™️. We should also test whether the WebSocket connection is closed when the user closes the app (or leaves ChatScreen). Head back to the main.swift file of the server project. Currently our WebSocket listener looks like this:

app.webSocket("chat") { req, client in
	print("Connected:", client)
}

Add a handler to the .onClose of client, performing nothing but a simple print():

app.webSocket("chat") { req, client in
	print("Connected:", client)

	client.onClose.whenComplete { _ in
		print("Disconnected:", client)
	}
}

Re-run the server and start the chat app. Once the app is connected, close the app (actually exit it, don’t just put it in the background). The Xcode console of the server should now print Disconnected: WebSocketKit.WebSocket. This confirms that WebSocket connections are indeed closed when we no longer care about them. Thus the server should have no dead connections lingering in memory.

Sending and receiving messages

You ready to actually send something to the server? Boy, I sure am. But just for a moment, let’s put on the brakes and think for a second. Lean back in the chair and stare aimlessly, yet somehow purposefully at the ceiling…

What exactly will be we sending to the server? And, just as importantly, what will we be receiving back from the server?

Your first thought may be “Well, just text, right?”, you’d be half right. But what about the time of the message? What about the sender’s name? What about an identifier to make the message unique from any other message? We don’t have anything for the user to create a username or anything just yet. So let’s put that to the side and just focus on sending and receiving messages.

We’re going to have to make some adjustments on both the app- and server-side. Let’s start with the server.

Server-side

Create a new Swift file in Sources/ChatServer called Models.swift in the server project. Paste (or type) the following code into Models.swift:

import Foundation

struct SubmittedChatMessage: Decodable { // 1
	let message: String
}

struct ReceivingChatMessage: Encodable, Identifiable { // 2
	let date = Date() // 3
	let id = UUID() // 4
	let message: String // 5
}

Here’s what’s going on:

1. This will be the data the server receives from individual clients when they send a message. For now, it’s just a message (String). Username et al will be added later on. Because we’re only receiving this type of data, we only need to decode it. Hence the Decodable protocol.
2. This will be the data sent to indiviual clients. Because we only have to encode it, it’s conforming to the Encodable protocol.
3. The date of the message. This will be automatically generated when initializing a ReceivingChatMessage.
4. A unique identifier for the message. Just like the date, this too will be automatically generated.
5. The message received earlier, now being sent to all the clients connected to the server.

Do note how we’re generating the date and id on the server-side. This makes the server the Source of Truth. The server knows what time it is. If the date were to be generated on the client-side, it cannot be trusted. What if the client has their clock setup to be in the future? Having the server generate the date makes its clock the only reference to time.

Timezones?

Swift’s Date object always has 00:00:00 UTC 01-01-2001 as absolute reference time. When initializing a Date or format one to string (e.g. via DateFormatter), the client's locality will be taken into consideration automatically. Adding or subtracting hours depending on the client's timezone.

UUID?

Universally Unique Identifiers are globally regarded as acceptable values for identifiers.

We also don’t want the client to send multiple messages with the same unique identifier. Whether accidentally or purposefully maliciously. Having the server generate this identifier is one extra layer of security and less possible sources of errors.

Now then. When the server receives a message from a client, it should pass it along to every other client. This does, however, mean we have to keep track of every client that’s connected.

Back to main.swift of the server project. Right above app.webSocket("chat") put the following declaration:

var clientConnections = Set<WebSocket>()

This is where we’ll store our client connections.

But wait… You should be getting a big, bad, nasty compile error. That’s because the WebSocket object does not conform to the Hashable protocol by default. No worries though, this can be easily (albeit cheapishly) implemented. Add the following code at the very bottom of main.swift:

extension WebSocket: Hashable {
	public static func == (lhs: WebSocket, rhs: WebSocket) -> Bool {
		ObjectIdentifier(lhs) == ObjectIdentifier(rhs)
	}
	
	public func hash(into hasher: inout Hasher) {
		hasher.combine(ObjectIdentifier(self))
	}
}

Badabing badaboom. The above code is a quick but simple way to make a class conform to Hashable (and by definition also Equatable), by simply using its memory address as a unique property. Note: this only works for classes. Structs will require a little more hands-on implementation.

Alright, so now that we’re able to keep track of clients, replace everything of app.webSocket("chat") (including its closure and its contents) with the following code 👇:

app.webSocket("chat") { req, client in
	clientConnections.insert(client)
	
	client.onClose.whenComplete { _ in
		clientConnections.remove(client)
	}
}

When a client connects, store said client into clientConnections. When the client disconnects, remove it from the same Set. Ezpz.

The final step in this chapter is adding the heart of the server↔️app communication. Below the entirety of client.onClose.whenComplete - but still inside the app.webSocket("chat") closure - add the following snippet of code:

Again, from the top:

1. Bind an .onText handler to the connected client.
   Everytime the server receives text from this client, this handler will be called. Here we have the opportunity to parse and validate the incoming text.
2. Decode the incoming message.
   This will be our validation step. We don’t want to continue if the client sends unacceptable payloads.
3. Initialize a ReceivingChatMessage with the message received from the client.
   Remember that the date and unique identifier of ReceivingChatMessage will be generated automatically.
4. Encode the ReceivingChatMessage to a JSON string (well, as Data).
5. Send the encoded JSON string to every client.
   Yes, this includes sending it to the original sender as well.

Why send it back?

We can use this as a confirmation that the message was, in fact, received successfully from the client. The app will receive back the message just like it’d receive any other message. This will prevent us from having to write additional code later on.

Done! The server is ready to receive messages and pass them along to other connected clients. Run the server and let it idle in the background, as we continue with the app!

Sending client-side

Rememeber those SubmittedChatMessage and ReceivingChatMessage structs we made for the server? We need them for the app as well. Create a new Swift file and name it Models.swift. Though you could just copy-paste the implementations, they will require a bit of modification:

import Foundation

struct SubmittedChatMessage: Encodable {
	let message: String
}

struct ReceivingChatMessage: Decodable, Identifiable {
	let date: Date
	let id: UUID
	let message: String
}

Notice how the Encodable and Decodable protocols have been swapped. It only makes sense: in the app, we only encode SubmittedChatMessage and only decode ReceivingChatMessage. The opposite of the server. We also removed the automatic initializations of date and id. The app has no business generating these.

Okay, back to ChatScreenModel (whether it's in a separate file or at the bottom of ChatScreen.swift). Add the top, but inside ChatScreenModel add the following instance property:

@Published private(set) var messages: [ReceivingChatMessage] = []

This where we’ll store received messages. Thanks to @Published, the ChatScreen will know exactly when this array gets updated and will react to this change. private(set) makes sure only ChatScreenModel can update this property. (After all, it's the owner of the data. No other object has any business modifying it directly!)

Still inside ChatScreenModel, add the following method:

func send(text: String) {	
	let message = SubmittedChatMessage(message: text) // 1
	guard let json = try? JSONEncoder().encode(message), // 2
		let jsonString = String(data: json, encoding: .utf8)
	else {
		return
	}
	
	webSocketTask?.send(.string(jsonString)) { error in // 3
		if let error = error {
			print("Error sending message", error) // 4
		}
	}
}

It seems self-explanatory. But for consistency’s sake:

1. Create the payload we’ll be sending to the server:
   A SubmittedChatMessage that, for now, just holds the message.
2. Turn our payload into a JSON string.
3. Send the JSON string to the server.
4. If any errors occurred, simply print the error.
   Of course, in a real app you’d respond a bit more respectfully to such an error. 🙃

Open ChatScreen.swift and add the following method to ChatScreen:

private func onCommit() {
	if !message.isEmpty {
		model.send(text: message)
		message = ""
	}
}

This method will be called when the user either presses the submit button or when pressing Return on the keyboard. Though it’ll only send the message if it actually contains anything.

In the .body of ChatScreen, locate the TextField and Button, then replace them (but not their modifiers or contents) with the following initializations:

TextField("Message", text: $message, onEditingChanged: { _ in }, onCommit: onCommit)
	// .modifiers here

Button(action: onCommit) {
	// Image etc
}
// .modifiers here

When the Return key is pressed while the TextField is focused, onCommit will be called. Same goes for when the Button is pressed by the user. TextField also requires an onEditingChanged argument - but we discard that by giving it an empty closure.

Now is the time to start testing what we have. Make sure the server is still running in the background. Place some breakpoints in the client.onText closure (where the server reads incoming messages) in main.swift of the server. Run the app and send a message. The breakpoint(s) in main.swift should be hit upon receiving a message from the app. If it did, 🎊 lush! 🎊 If not, well... retrace your steps and start debugging!

Receiving client-side

Sending messages is cute and all. But what about receiving them? (Well, technically we are receiving them, just never reacting to them.) Right you are!

Let’s visit ChatScreenModel once more. Remember that onReceive(incoming:) method? Replace it and give it a sibling method as shown below:

So…

1. Those receive handlers we bind to URLSessionWebSocketTask? They only work once. Thus, we instantly rebind a new handler, so we're ready to read the next incoming message.
2. If successful, we pick out the contents of the message and let another method deal with it further.
3. If not successful, simply print an error to the console.
4. This method is responsible for parsing the incoming (successful) message.
5. A WebSocket message can be either binary or text. So far we’ve been sending JSONs back and forther — which are text formats (more on this later). Thus we only handle messages containing strings. Afterwards we decode the data to ReceivingChatMessage.
6. Plop the decoded message into self.messages. However, because URLSessionWebSocketTask can call the receive handler on a different thread, and because SwiftUI only works on the main thread, we have to wrap our modification in a DispatchQueue.main.async {}, assuring we're actually performing the modification on the main thread.

Explaining the hows and whys of working with different threads in SwiftUI is beyond the scope of this tutorial.

Nearly there!

Check back in on ChatScreen.swift. See that empty ScrollView? We can finally populate it with messages:

ScrollView {
	LazyVStack(spacing: 8) {
		ForEach(model.messages) { message in
			Text(message.message)
		}
	}
}

It’s not going to look spectacular by any means. But this’ll do the job for now. We simply represent every message with a plain o’ Text.

Go ahead, run the app. When you send a message, it should instantly appear on the screen. This confirms the message was successfully sent to the server, and the server successfully sent it back to the app! Now, if you can, open up multiple instances of the app (tip: use different Simulators). There’s virtually no limit to the amount of clients! Have a nice big chat party all by yourself.

Keep sending messages until there’s no room left on the screen. Notice anything? Yarp. The ScrollView doesn't automatically scroll to the bottom once new messages are beyond the screen's bounds. 😟

Enter…

Autoscrolling

Remember, the server generates a unique identifier for each message. We can finally put it to good use! The wait was worth it for this incredible payoff, I assure you.

In ChatScreen, turn the ScrollView into this beauty:

ScrollView {
	ScrollViewReader { proxy in // 1
		LazyVStack(spacing: 8) {
			ForEach(model.messages) { message in
				Text(message.message)
					.id(message.id) // 2
			}
		}
		.onChange(of: model.messages.count) { _ in // 3
			scrollToLastMessage(proxy: proxy)
		}
	}
}

Then add the following method:

private func scrollToLastMessage(proxy: ScrollViewProxy) {
	if let lastMessage = model.messages.last { // 4
		withAnimation(.easeOut(duration: 0.4)) {
			proxy.scrollTo(lastMessage.id, anchor: .bottom) // 5
		}
	}
}

1. We’re wrapping the contents of the ScrollView in a ScrollViewReader.
   The ScrollViewReader provides us with a proxy that we'll need very soon.
2. Give each message a unique identifier (simply using the message’s identifier).
3. Keep track of changes to model.messages.count. When this value changes, we call the method we just added, passing it the proxy provided by ScrollViewReader.
4. Safely get the latest message.
5. Call the .scrollTo(_:anchor:) method of the ScrollViewProxy. This tells the ScrollView to scroll to the View with the given identifier. We wrap this in withAnimation {} to animate the scrolling.

Et voilà…

Adding user information

These messages are pretty lush… but it’d be even lush-er if we knew who sent the messages and visually distinguish between received and sent messages.

With each message we will also attach a username and a user identifier. Because a username isn’t enough to identify a user, we need something unique. What if the user and everyone else’s name was Patrick? We’d have an identity crisis and would be unable to distinguish between messages sent by Patrick and messages received by a Patrick.

As is tradition, we start with the server, it’s the least amount of work.

Open up Models.swift where we defined both SubmittedChatMessage and ReceivingChatMessage. Give both of these bad boys a user: String and userID: UUID property, like so:

struct SubmittedChatMessage: Decodable {
	let message: String
	let user: String // <- We
	let userID: UUID // <- are
}

struct ReceivingChatMessage: Encodable, Identifiable {
	let date = Date()
	let id = UUID()
	let message: String
	let user: String // <- new
	let userID: UUID // <- here
}

(Don’t forget to update the Models.swift file in the app’s project as well!)

Returning to main.swift, where you should be greeted with an error, change the initialization of ReceivingChatMessage to the following:

let outgoingMessage = ReceivingChatMessage(
	message: incomingMessage.message,
	user: incomingMessage.user,
	userID: incomingMessage.userID
)

And that's it! We're done with the server. It's just the app from here on out. The home stretch!

In the app's Xcode project, create a new Swift file called UserInfo.swift. Place the following code there:

import Combine
import Foundation

class UserInfo: ObservableObject {
	let userID = UUID()
	@Published var username = ""
}

This will be our EnvironmentObject where we can store our username in. As always, the unique identifier is an automatically generated immutable UUID. Where does the username come from? The user will input this when opening the app, before being presented the chat screen.

New file time: SettingsScreen.swift. This file will house the simple settings form:

1. The previously created UserInfo class will be accessible here as an EnvironmentObject.
2. A simple validation to make sure the username isn’t just whitespace.
3. The TextField will directly write its contents into userInfo.username.
4. The NavigationLink that will present ChatScreen when pressed. The button is disabled while the username is invalid. (Do you notice how we initialize ChatScreen in the NavigationLink? Had we made ChatScreen connect to the server in its init(), it would've done so right now!)

If you wish you can add a little panache to screen. 😉

Since we’re using SwiftUI’s navigation features, we need to start off with a NavigationView somewhere. ContentView is the perfect spot for this. Change ContentView's implementation as follows:

struct ContentView: View {
	@StateObject private var userInfo = UserInfo() // 1
	
        var body: some View {
		NavigationView {
			SettingsScreen()
		}
		.environmentObject(userInfo) // 2
		.navigationViewStyle(StackNavigationViewStyle())// 3
    }
}

1. We initialize an instance of UserInfo and...
2. … pass it along as an EnvironmentObject, making it accessible to all succeeding views.
3. This is just to make the app not use a columned navigation view on certain screen sizes.

Now to send the data of UserInfo along with the messages we send to the server. Go to ChatScreenModel (wherever you put it). At the top of the class add the following properties:

final class ChatScreenModel: ObservableObject {
	private var username: String?
	private var userID: UUID?

	// the rest ...
}

The ChatModelScreen should receive these values when connecting. It's not ChatModelScreen's job to know where this information came from. If, in the future, we decide to change where both username and userID are stored, we can leave ChatModelScreen untouched.

Change the connect() method to accept these new properties as arguments:

func connect(username: String, userID: UUID) {
	self.username = username
	self.userID = userID

	// etc ...
}

Finally, in send(text:), we need to apply these new values to the SubmittedChatMessage we're sending to the server:

func send(text: String) {
	guard let username = username, let userID = userID else {
		return
	}
	
	let message = SubmittedChatMessage(message: text, user: username, userID: userID)
	// Everything else ...
}

Aaaand that’s it for ChatScreenModel. It's finished. 😙👌

For the final time, open up ChatScreen.swift. At the top of ChatScreen add:

@EnvironmentObject private var userInfo: UserInfo

Don’t forget to supply the username and userID to ChatScreenModel when the view appears:

private func onAppear() {
	model.connect(username: userInfo.username, userID: userInfo.userID)
}

Now, once again, as practiced: Lean back in that chair and look up at the ceiling. What should the text messages look like? If you’re in no mood for creative thinking, you can use the following View that represents a single received (and sent) message:

It’s not particularly exciting looking. Here’s what it looks like on an iPhone:

(Remember how the server also sends the date of a message? Here it’s used to display the time.)

Colors and positioning are based on the isUser property that's passed down by the parent. In this case, that parent is none other than ChatScreen. Because ChatScreen has access to the messages as well as the UserInfo, it's there where the logic is placed to determine whether the message belongs to the user or not.

ChatMessageRow replaces the boring Text we used before to represent messages:

ScrollView {
	ScrollViewReader { proxy in
		LazyVStack(spacing: 8) {
			ForEach(model.messages) { message in
				// This one right here 👇, officer.
				ChatMessageRow(message: message, isUser: message.userID == userInfo.userID)
					.id(message.id)
			}
		}
		// etc.
	}
}

Welcome to the finish line! You’ve made it all the way here! For the final time, ▶️ run the app and chat away.

By now you should have a primitive — but fuctioning — chat app. As well as a server handling the incoming and outgoing messages. All written in Swift!

Congrats! And thank you very much for reading! 🎊

You can download the final code from Github.

Recap

Let’s sum up our journey:

• We created a server as a Swift Package executable.
• We used the Vapor web framework to listen to WebSocket connections.
• We programmed the server to receive, parse and send payloads to connected clients.
• We created a basic SwiftUI to send and render messages.
• We used the provided WebSocket APIs in Foundation to provide the communication with the server.

All that while completely staying within the Swift ecosystem. No extra programming languages, no Cocoapods or anything.

Final words

Of course, what we created here is only a fraction of a fraction of a complete, production ready chat app and server. We cut a lot of corners to save on time and complexity. Needless to say it should give a pretty basic understanding of how a chat app works.

Consider the following features to, perhaps, implement yourself:

• Multiple channels
  Our server basically accounts for just one channel to chat in. Everyone who connects joins the same party. Modern chat software (e.g. Discord, Slack and Teams) all allow for multiple channels for people to talk in. They even have private chats!
• Respectful autoscroll
  You may have noticed the scrollview now always scrolls to the bottom whenever a message is received. This is seriously annoying for users who manually scrolled up to read earlier messages. A respectful chat app only scrolls to the bottom automatically if the scrollview was already at the bottom.
• Splice the amount of messages in memory
  Currently, using the ForEach View, we iterate through every message in memory. Modern chat software only keep track of a handful of messages to render, and only load in older messages once the user scrolls up.
• Server messages
  It’s common courtesy to announce your arrival whenever you enter a party. A feature you see in all chat software are server-generated messages announcing people joining or leaving the party.

Final notes

That odd URLSessionWebSocketTask API
If you’ve ever worked with WebSockets before, you may share the opinion that Apple’s API for WebSocket’s are quite… non-traditional. You’re certainly not alone on this. Having to constantly rebind the receive handler is just odd. If you think you’re more comfortable using a more traditional WebSocket API for iOS and macOS then I would certainly recommend Starscream. It’s well tested, performant and works on older versions of iOS.

Bugs bugs bugs
This tutorial was written using Xcode 12 beta 5 and iOS 14 beta 5. Bugs appear and disappear between each new beta version. It is unfortunately impossible to predict what will and what won’t work in future (beta) releases.

Appendix A: running on physical device

The server not only runs on your local machine, it’s only accessible from your local machine. This isn’t a problem when running the app in Simulator (or as macOS app on the same machine). But running the app on a physical device, or on a different Mac, the server will have to be made accessible in your local network.

To do this, in main.swift of the server code, add the following line directly after initializing the Application instance:

app.http.server.configuration.hostname = "0.0.0.0"

Now in ChatScreenModel, in the connect(username:userID:) method, you need to change the URL to match your machine's local IP:

let url = URL(string: "ws://127.0.0.1:8080/chat")!
                          //^^this^^^

Your machine’s local IP can be found in various ways. Personally I always just open System Preferences > Network, where the IP is directly shown, ready to be selected and copied.

It should be noted that the success rate of this varies between networks. There are a lot of factors (like security) that could prevent this from working.

Thank you so much for reading! If you have any opinions on this piece, thoughts for improvements, or found some errors, please, please, please let me know! I will do my very best to continuously improve this tutorial. 🙂