There are four widget families that can be displayed on unlocked device\u2019s screen (together with apps):<\/p>\n\n\n\n
- \n
- systemSmall<\/li>\n\n\n\n
- systemMedium<\/li>\n\n\n\n
- systemLarge<\/li>\n\n\n\n
- SystemExtraLarge<\/li>\n<\/ul>\n\n\n\n
And four accessory families which can be displayed Apple Watch or iOS device\u2019s Lock Screen:<\/p>\n\n\n\n
- \n
- accessoryCircle<\/li>\n\n\n\n
- accessoryRectangular<\/li>\n\n\n\n
- accessoryInline (contains a single text line and optional image)<\/li>\n\n\n\n
- accessoryCorner (WatchOS only)
<\/li>\n<\/ul>\n\n\n\nScreenshots below presents a different accessories appearance on iOS and WatchOS:<\/p>\n\n\n\n
![\"a](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-1-1.png\")
<\/a><\/figure>\n\n\n\nLock screen widgets are supporting those rendering modes:<\/p>\n\n\n\n
- \n
- vibrant,<\/li>\n\n\n\n
- full-colour,<\/li>\n\n\n\n
- accented.<\/li>\n<\/ul>\n\n\n\n
For iOS, there is available only vibrant mode which provides desaturated text, images and gauges in monochrome view for widgets. Check out the official documentation<\/a> to learn more.<\/p>\n\n\n\n
The image below shows how the widget appearance changes when the rendering mode is changed (from full-colour to accented blue colour):<\/p>\n\n\n\n
![\"how](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-2.png\")
<\/a><\/figure>\n\n\n\nThe widget family should be specific to the application and content size. An accent colour can be used to highlight the title and provide an aesthetically pleasing widget UI.<\/p>\n\n\n\n
Lock Screen widgets customization and limitations<\/strong><\/h2>\n\n\n\n
Widgets have many limitations. In Apple\u2019s documentation, we can find that we shouldn’t consider widgets as separate apps. It\u2019s just an extension to an existing app, and we can\u2019t implement functions like scrolling, buttons or other interactive mechanics. It should be a simple view with text and optional images.<\/p>\n\n\n\n
Building our little project and adding widgets to it, we encountered some limitations that we would like to share with you.<\/strong><\/p>\n\n\n\n
Constraints encountered in the project<\/strong><\/h3>\n\n\n\n
The first of them is the size of the entries array given in getTimeline<\/a> method. For example, updates will not work if the size of the array of objects of the type TimelineEntry<\/a> is too large (more than about 1000), but if there are about 100 of them, then everything works as expected).<\/p>\n\n\n\n
The next limitation is the frequency of updating the widget. There is a limit to updating the actual information about the widget, the update depends on the logic provided in the getTimeline<\/a> method and on the budget<\/a> of the widget calculated by WidgetKit. The budget is unique for each widget and the system takes into account many factors to calculate it. See the link<\/a> for detailed information about the budget.<\/p>\n\n\n\n
The third type of limitation is related to the UI representation of the widget. The developer must take care that the content fits correctly in the widget\u2019s frame and all-important information is visible to the user. When adding an image to a widget, the developer must pay attention that it will take up additional space, while the size of the widget will remain the same. There is also a limit on the size of the images. Empirically, it was found out that the widget will not work with a 1200x1200px image, while it works with its small version 120x120px.<\/p>\n\n\n\n
Lock Screen widget demo tutorial<\/strong><\/h2>\n\n\n\n
For the purpose of this article, we\u2019ve prepared a small demo app to show how widgets work and how easy is to implement one. We will focus on iOS <\/strong>only leaving WatchOS <\/strong>for another occasion.<\/p>\n\n\n\n
For the beginning, please download a starter app from GitHub or clone it from provided link<\/a> using Xcode 14 beta 1 or newer.<\/p>\n\n\n\n
* A disclaimer here<\/strong> \u2013 we used Xcode 14 beta 1 to build this project and there is a small chance that something will be not working or Apple will make some changes in code for the released version of Xcode or future betas.<\/p>\n\n\n\n
![\"screenshot](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-3.png\")
<\/a><\/figure>\n\n\n\nAfter you clone and run the project it should download quotas from the Internet and show it on devices or simulator\u2019s screen. This app was built to show you a quotation from a simple API<\/strong>. You can move between quotes by scrolling down or up on the screen. If you\u2019d like you can also share a quote using share button.<\/p>\n\n\n\n
Initial preparation<\/strong><\/h3>\n\n\n\n
After you play with the app, we can go to Xcode project and start building a simple widget that will get random quotes from API and show them on a widget outside the app. After chosen time period quotation will change for another. Let\u2019s start.<\/p>\n\n\n\n
![\"QuotesDemoApp\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Zrzut-ekranu-2022-06-24-o-18.49.52-1024x668-1.png\")
<\/a><\/figure>\n\n\n\nGo to project navigator and select your project name on the top. Next in general settings on the right press \u201c+\u201d to add a new target with widget.<\/p>\n\n\n\n
![\"Choose](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Zrzut-ekranu-2022-06-24-o-18.50.11-1024x668-1.png\")
<\/a><\/figure>\n\n\n\nEnter Product Name and do not check Include Configuration Intent<\/strong>, because we will not use it in this simple demo. We will use static configuration here.<\/p>\n\n\n\n
Intent configuration can be used for user-configurable properties that will for example change what data will be displayed by a widget or to allow automate your app using Siri and Shortcuts. Press Next.<\/p>\n\n\n\n
![\"Activate](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-7.png\")
<\/a><\/figure>\n\n\n\nXcode will probably ask you if you want to activate the scheme for our newly created widget for building and debugging. It is recommended to do so if we want to be able to test the code.<\/p>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Zrzut-ekranu-2022-06-24-o-19.09.00-1024x660-1.png\")
<\/figure>\n\n\n\nNow, we have our widget target added to the project. You can see new files on the left. I marked them with blue frame. We will get to the QuotesWidget.swift<\/strong> file in the moment. First select three files as shown on the screenshot above, and in File inspector on the right choose Target Membership <\/strong>for QuotesWidgetExtension<\/strong> also with QuotesDemoApp<\/strong>. This will allow using services, model and view model on both targets instead of creating the same files for all targets separately.<\/p>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-9.png\")
<\/a><\/figure>\n\n\n\nBuilding the widget<\/strong><\/h3>\n\n\n\n
We can now focus on building our widget. Go to QuotesWidget.swift<\/strong> and start with changing SimpleEntry <\/strong>struct to QuoteEntry <\/strong>for better readability. We will add a \u201clet quote: Quote<\/strong>\u201d to allow widget to get our quote data for displaying it on user\u2019s device.<\/p>\n\n\n\n
Let\u2019s look closer on QuoteEntry <\/strong>struct. It has to conform to TimelineEntry<\/strong><\/a> protocol. Widgets on iOS can be changed during time events or user action. Those structs are created to provide data for a timeline of views to be displayed at the appropriate time.<\/p>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-10-1.png\")
<\/a><\/figure>\n\n\n\nThe Provider Struct<\/strong><\/h3>\n\n\n\n
The Provider struct that conforms to TimeLineProvider<\/strong><\/a> protocol has three required methods that we will be using to tell widget when to send our data to the view and how to update it.<\/p>\n\n\n\n
- \n
- placeholder(in: )<\/strong><\/a>method is providing data for widget\u2019s placeholder UI which is the temporary content of your widget. This method is usually called when for example device\u2019s environment changes occur like change of dynamic type setting. System may reload your widget and use placeholder data. In this case we are using example quote written in code to quickly acquire necessary data.<\/li>\n\n\n\n
- getSnapshot(for: )<\/strong><\/a> is used to create a single data snapshot for your widget. Snapshot is where the system needs to quickly display a single entry. Data from this method is used for example on widget gallery, when user can choose a widget to be displayed on the home screen. We\u2019re also using an example quote here were needed fast access to data to quickly return a view.<\/li>\n\n\n\n
- getTimeline(in: )<\/strong><\/a> method contains an array of entries and rules when they should be displayed on widget. Timelines are a combination of views and dates that are returned, which allow you to decide at what time a particular view should be shown.<\/li>\n<\/ul>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-11-1.png\")
<\/a><\/figure>\n\n\n\nIn our example we used asynchronous function running on main thread to get quotes, put them in array of QuoteEntry <\/strong>objects and manipulate date objects to allow widget to show a new quote every 10 seconds. Feel free to use different time interval or change the method to display quotes in a different way.<\/p>\n\n\n\n
Timeline<\/strong><\/h3>\n\n\n\n
Timeline<\/strong><\/a> object from method getTimeline<\/strong><\/a> creates a timeline with quote entries and a policy how to create a new timeline when actual one used the last object in the array. We can choose how new timeline gets created: after selected date, after using last entry from the array (used in this case) and after user interaction within the app.<\/p>\n\n\n\n
Widget options and the view<\/strong><\/h3>\n\n\n\n
When we created our placeholder, snapshot and timeline, we can configure widget options and the view.<\/p>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-12.png\")
<\/a><\/figure>\n\n\n\nIn main widget struct we can set widget\u2019s configuration and settings. It uses configuration and provider to populate the view with data we provided earlier.<\/p>\n\n\n\n
- \n
- The kind: String<\/strong><\/a> variable is an exclusive name for this widget which should be different from our other widgets names.<\/li>\n\n\n\n
- A .configurationDisplayName<\/strong><\/a>shows a name of our widget on device screen.<\/li>\n\n\n\n
- A .description<\/strong><\/a> as name suggest should be a short description what our widget is about.<\/li>\n\n\n\n
- .supportedFamilies<\/strong><\/a> method tells the widget what sizes it should be using on main screen. We are using .systemSmall<\/strong><\/a> and .systemMedium<\/strong><\/a> to present small square widget to the user and rectangular medium size widget.<\/li>\n<\/ul>\n\n\n\n
We can also use some new types for supported families that ware announced with iOS 16. We will get back to it later.<\/p>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-13.png\")
<\/a><\/figure>\n\n\n\nAs for a view, we are using standard SwiftUI <\/strong>components, separate for each system family we\u2019re using to allow rendering different components for each view. This is quite normal procedure, because different family can contain different amount of text and images.<\/p>\n\n\n\n
Please, feel free to build a view for .systemLarge<\/strong><\/a> type of family and see how it is different from medium and small.<\/p>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-14.png\")
<\/a><\/figure>\n\n\n\nIf you have problems with setting up the preview for a view in canvas, you can use this code above.<\/p>\n\n\n\n
![\"Screens](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-15.png\")
<\/a><\/figure>\n\n\n\n<\/div>\n\n\n\nAdding new widget to the home screen<\/strong><\/h3>\n\n\n\n
Now you can add your new widget to the home screen. If it\u2019s not appearing in widget gallery, just put its name in a search field.<\/p>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-16.png\")
<\/a><\/figure>\n\n\n\nIf we want to use a new API for iOS 16 that shows widgets on the lock screen, we just need to add a new family type to supported families and update the view.<\/p>\n\n\n\n
A rectangular widget can display text and a small image.<\/p>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-17.png\")
<\/a><\/figure>\n\n\n\nWe can add a new case<\/strong> to our view that will be displayed on a lock screen widget.<\/p>\n\n\n\n
ViewThatFits<\/strong><\/a> adapts to available space and use it all for children views. This way text will fill all available widget\u2019s space.<\/p>\n\n\n\n
![\"Screens](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-18.png\")
<\/a><\/figure>\n\n\n\n<\/div>\n\n\n\nAdding widget to the lock screen<\/strong><\/h2>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-19.png\")
<\/a><\/figure>\n\n\n\n![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-20.png\")
<\/a><\/figure>\n\n\n\n![\"Screen](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-21.png\")
<\/a><\/figure>\n\n\n\nBy adding .accessoryInline<\/strong><\/a>we can now add an inline widget on lock screen. This widget just shows a single line of text and an optional image at the top of the screen.<\/p>\n\n\n\n
![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-22.png\")
<\/a><\/figure>\n\n\n\n![\"code\"](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-23.png\")
<\/a><\/figure>\n\n\n\nAdding .accessoryCircular<\/strong><\/a> allows us to use circular widgets with text, image or a new Gauge<\/a> view, which we are using here.<\/p>\n\n\n\n
![\"Screen](\"https:\/\/sii.ua\/blog\/wp-content\/uploads\/2024\/01\/Ryc.-24.png\")
<\/a><\/figure>\n\n\n\nUsing a circular widget and gauge you can show a value represented in some sort of value in a declared range in a circular way or linear if we use another accessory family.<\/p>\n\n\n\n
Conclusion<\/strong><\/h2>\n\n\n\n
Apple has done a great job with widgets on the Lock Screen for iOS devices, adding improvements, personalization, and live activities. With the right approach to creation, the Lock Screen widgets can significantly improve the user experience and provide greater ease of use. As we just build a widget ourselves, we can now write that the API is very friendly to developers and easy to implement.<\/p>\n\n\n\n
Many thanks to Damian Drohobycki and Marta Mazurek for an inspiration to write this article, technical review and support.<\/em><\/p>\n\n\n
- A .configurationDisplayName<\/strong><\/a>shows a name of our widget on device screen.<\/li>\n\n\n\n
- getSnapshot(for: )<\/strong><\/a> is used to create a single data snapshot for your widget. Snapshot is where the system needs to quickly display a single entry. Data from this method is used for example on widget gallery, when user can choose a widget to be displayed on the home screen. We\u2019re also using an example quote here were needed fast access to data to quickly return a view.<\/li>\n\n\n\n
- placeholder(in: )<\/strong><\/a>method is providing data for widget\u2019s placeholder UI which is the temporary content of your widget. This method is usually called when for example device\u2019s environment changes occur like change of dynamic type setting. System may reload your widget and use placeholder data. In this case we are using example quote written in code to quickly acquire necessary data.<\/li>\n\n\n\n