PageControl
PageControl is a set of themed styles for the native UIPageControl component with primary and secondary variants.
Platform availability: iOS 17.0+
When to use:
- Use PageControl when displaying paginated content such as onboarding flows, carousels, or image galleries where users need to know their position.
- Consider alternative navigation patterns when the number of pages exceeds 7-10, as page indicators become less useful with many dots.
It includes the following features:
- Primary style for use on primary background colors.
- Secondary style for use on surface primary colors.
- Consistent tint colors from the design system.
- Alpha-based unselected indicator styling.
Import
import BackbaseDesignSystem
Visual reference
|
|
|
|
|
|
|
|
API reference
primaryPageControl
The primaryPageControl style is applied to a UIPageControl placed on top of a primary background color.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
currentPageIndicatorTintColor |
UIColor |
The Theme.colors.onBackground.brand color for the current page indicator |
|
pageIndicatorTintColor |
UIColor |
The Theme.colors.onBackground.brand color at 30% alpha for unselected indicators |
secondaryPageControl
The secondaryPageControl style is applied to a UIPageControl placed on top of a surfacePrimary color.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
currentPageIndicatorTintColor |
UIColor |
The Theme.colors.foreground.default color for the current page indicator |
|
pageIndicatorTintColor |
UIColor |
The Theme.colors.foreground.default color at 40% alpha for unselected indicators |
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
currentPage |
Int |
0 |
|
numberOfPages |
Int |
0 |
currentPage
The currentPage property controls which page indicator is highlighted.
let pageControl = UIPageControl()
pageControl.currentPage = 2
numberOfPages
The numberOfPages property sets the total number of page indicators displayed.
let pageControl = UIPageControl()
pageControl.numberOfPages = 5
Usage
Basic usage
Apply the primary or secondary page control style to a standard UIPageControl.
Primary page control
let pageControl = UIPageControl()
pageControl.numberOfPages = 5
pageControl.currentPage = 0
DesignSystem.shared.styles.primaryPageControl(pageControl)
view.addSubview(pageControl)
Secondary page control
let pageControl = UIPageControl()
pageControl.numberOfPages = 3
pageControl.currentPage = 1
DesignSystem.shared.styles.secondaryPageControl(pageControl)
view.addSubview(pageControl)
With a scroll view
class OnboardingViewController: UIViewController {
private let scrollView = UIScrollView()
private let pageControl = UIPageControl()
override func viewDidLoad() {
super.viewDidLoad()
scrollView.isPagingEnabled = true
scrollView.delegate = self
pageControl.numberOfPages = 4
DesignSystem.shared.styles.primaryPageControl(pageControl)
pageControl.addTarget(self, action: #selector(pageControlChanged), for: .valueChanged)
view.addSubview(scrollView)
view.addSubview(pageControl)
}
@objc private func pageControlChanged() {
let offset = CGFloat(pageControl.currentPage) * scrollView.frame.width
scrollView.setContentOffset(CGPoint(x: offset, y: 0), animated: true)
}
}
extension OnboardingViewController: UIScrollViewDelegate {
func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) {
let page = Int(scrollView.contentOffset.x / scrollView.frame.width)
pageControl.currentPage = page
}
}
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.primaryPageControl |
For use on primary background colors |
|
DesignSystem.shared.styles.secondaryPageControl |
For use on surface primary colors |
Custom styling
let customPageControlStyle: Style<UIPageControl> = { pageControl in
pageControl.pageIndicatorTintColor = UIColor.gray.withAlphaComponent(0.3)
pageControl.currentPageIndicatorTintColor = Theme.colors.background.brand
}
Accessibility
This component is built with accessibility in mind. See the information below for supported behaviors and configuration options to ensure a fully accessible experience for all users.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
accessibilityLabel |
The accessible label describing the page control |
String |
|
accessibilityValue |
The current page and total pages (automatically set) |
String |
Best practices
- UIPageControl has built-in accessibility support.
- VoiceOver announces the current page and total pages.
- Users can swipe to change pages when focused.
- Consider setting a descriptive accessibilityLabel for context.
let pageControl = UIPageControl()
pageControl.numberOfPages = 4
pageControl.accessibilityLabel = "Onboarding pages"
DesignSystem.shared.styles.primaryPageControl(pageControl)
Dependencies
- External dependencies: None
- Internal dependencies: Theme.colors
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
This component uses semantic tokens only. See Semantic tokens below.
Semantic tokens
These tokens are accessed via the public DesignSystem.shared API.
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors.foreground.brand |
Current page indicator color |
|
Colors |
Theme.colors.foreground.default |
Secondary style indicator (40% alpha for unselected) |
|
Colors |
Theme.colors.foreground.subtle |
Unselected page indicator color |
|
Colors |
Theme.colors.onBackground.brand |
Primary style indicator (30% alpha for unselected) |
|
Styles |
DesignSystem.shared.styles.primaryPageControl |
Primary page control style |
|
Styles |
DesignSystem.shared.styles.secondaryPageControl |
Secondary page control style |