Getting started with UIButton.Configuration on iOS

UIButton.Configuration API was introduced in WWDC’21 with a goal of making it easier to create buttons with many styles, sizes, colours etc. Configurations API comes with functions for creating common button configurations: filled(), bordered(), borderedProminent(), borderedTinted(), borderless(), plain(), gray(), tinted(). These configurations can be further customized. One benefit of the API is that it will take care of different states of the button like highlighted, disabled, hovered and so on and applies different styling based on the state. Most of the time that is all we needed, but additionally we can also adjust styling for different states as well through the configurationUpdateHandler().

The basic usage of the API involves in creating a UIButton.Configuration object and passing it to UIButton init function of setting it to UIButton’s configuration property. The button will then apply the configuration. In WWDC session it was emphasized that applying a new configuration is cheap and optimized behind the scenes therefore we should never compare the new configuration with the one currently applied on the button.

	var configuration = UIButton.Configuration.filled() // or .plain() or something else
	configuration.baseBackgroundColor = .systemCyan
	configuration.buttonSize = .large
	configuration.cornerStyle = .dynamic
	configuration.showsActivityIndicator = false
	configuration.image = UIImage(systemName: "pencil")
	configuration.imagePlacement = .trailing
	configuration.imagePadding = 6
	configuration.title = "Title"
	configuration.titleAlignment = .leading
	configuration.titlePadding = 10
	configuration.subtitle = "Subtitle"
	// and more

	button.configuration = configuration
	// or
	let button2 = UIButton(configuration: configuration, primaryAction: action)

view raw Configuration.swift hosted with ❤ by GitHub

Example of button configurations when the tint colour is set to red.

For getting a better overview on how default configurations change based on the properties, we set on UIButton.Configuration type, I built a simple preview app which takes configurations: filled(), bordered(), borderedProminent(), borderedTinted(), borderless(), plain(), gray(), tinted() and applies some modifications on these. The results are shown below.

	private func configurations(forStyleIndex index: Int) -> [UIButton.Configuration] {
	var configuration1 = UIButton.Configuration.filled()
	configuration1.title = "Filled"
	var configuration2 = UIButton.Configuration.tinted()
	configuration2.title = "Tinted"
	var configuration3 = UIButton.Configuration.gray()
	configuration3.title = "Gray"
	var configuration4 = UIButton.Configuration.plain()
	configuration4.title = "Plain"
	var configuration5 = UIButton.Configuration.bordered()
	configuration5.title = "Bordered"
	var configuration6 = UIButton.Configuration.borderedProminent()
	configuration6.title = "Bordered Prominent"
	var configuration7 = UIButton.Configuration.borderedTinted()
	configuration7.title = "Bordered Tinted"
	var configuration8 = UIButton.Configuration.borderless()
	configuration8.title = "Borderless"

	let all: [UIButton.Configuration] = [configuration1, configuration2, configuration3, configuration4, configuration5, configuration6, configuration7, configuration8]
	.map({ original in
	var configuration = original
	switch index {
	case 0:
	break
	case 1:
	configuration.subtitle = "Subtitle"
	case 2:
	configuration.image = UIImage(systemName: "pencil")
	case 3:
	configuration.buttonSize = .large
	case 4:
	configuration.image = UIImage(systemName: "pencil")
	configuration.imagePlacement = .trailing
	case 5:
	configuration.baseBackgroundColor = .systemBlue
	case 6:
	configuration.buttonSize = .mini
	case 7:
	configuration.showsActivityIndicator = true
	case 8:
	configuration.baseBackgroundColor = .systemCyan
	configuration.buttonSize = .large
	configuration.cornerStyle = .dynamic
	configuration.showsActivityIndicator = false
	configuration.image = UIImage(systemName: "pencil")
	configuration.imagePlacement = .trailing
	configuration.imagePadding = 6
	configuration.titleAlignment = .leading
	configuration.titlePadding = 10
	configuration.subtitle = "Subtitle"
	default:
	fatalError("Implement")
	}
	return configuration
	})
	return all
	}