Available from v1.12.0
IconButton
IconButton is a round button component that displays an icon with an optional label positioned above or below the button.
Platform availability: iOS 17.0+
When to use:
- Use IconButton when you need a circular icon-based action button with an optional text label.
- Consider using a standard Button when you need a rectangular button with text.
It includes the following features:
- Configurable icon image with optional title label.
- Label placement options (top, bottom, or no title).
- Loading and disabled state support.
- Predefined primary and danger styles.
Import
UIKit framework
import BackbaseDesignSystem
Visual reference
Default |
Disabled |
Loading |
API reference
IconButton
Properties
|
Property |
Type |
Description |
|---|---|---|
|
button |
Button |
The button is the round button used to display the icon (read-only) |
|
disabledColor |
UIColor |
The disabledColor is the color of the title in disabled state. Defaults to Theme.colors.foreground.disabled |
|
icon |
UIImage? |
The icon image displayed in the button. Defaults to nil |
|
isEnabled |
Bool |
The isEnabled determines whether the button responds to user interaction. Defaults to true |
|
isLoading |
Bool |
The isLoading displays a loading indicator when true. Defaults to false |
|
label |
UILabel |
The label displays the title text (read-only) |
|
labelPlacement |
LabelPlacement |
The labelPlacement determines the label position relative to the button. Defaults to .bottom |
|
normalColor |
UIColor |
The normalColor is the background and title color in normal state |
|
stackView |
UIStackView |
The stackView contains the button and label (read-only) |
|
title |
String? |
The title text displayed in the label. Defaults to nil |
Initializers
init(frame:)
Creates an IconButton with the default primary style and specified frame.
|
Parameter |
Type |
Description |
|---|---|---|
|
frame |
CGRect |
The frame rectangle for the view |
init(frame:style:)
Creates an IconButton with a specified style and frame.
|
Parameter |
Type |
Description |
|---|---|---|
|
frame |
CGRect |
The frame rectangle for the view |
|
style |
Style<IconButton> |
The style to apply to the icon button |
LabelPlacement
An enumeration defining the label position relative to the button.
|
Case |
Description |
|---|---|
|
.bottom |
The label is placed below the button |
|
.noTitle |
The label is removed |
|
.top |
The label is placed above the button |
Usage
Basic usage
let iconButton = IconButton()
iconButton.icon = UIImage(systemName: "heart")
iconButton.title = "Favorite"
Advanced usage
let customIconButton = IconButton(style: DesignSystem.shared.styles.dangerIconButton)
customIconButton.icon = UIImage(systemName: "trash")
customIconButton.title = "Delete"
customIconButton.labelPlacement = .top
customIconButton.isEnabled = true
Icon-only button
let iconOnlyButton = IconButton()
iconOnlyButton.icon = UIImage(systemName: "plus")
iconOnlyButton.labelPlacement = .noTitle
States and variants
Loading
The loading state displays a loading indicator in place of the icon.
iconButton.isLoading = true
iconButton.isLoading = false
Disabled
The disabled state reduces opacity and prevents user interaction.
iconButton.isEnabled = false
iconButton.isEnabled = true
Label placement
iconButton.labelPlacement = .top
iconButton.labelPlacement = .bottom
iconButton.labelPlacement = .noTitle
Customization
Styling
|
Style |
Description |
|---|---|
|
DesignSystem.shared.styles.primaryIconButton |
Primary action button with brand colors |
|
DesignSystem.shared.styles.dangerIconButton |
Destructive action button |
Custom styling
let customStyle: Style<IconButton> = { iconButton in
iconButton.button.cornerRadius = .medium()
iconButton.normalColor = .systemPurple
iconButton.label.font = DesignSystem.shared.fonts.preferredFont(.caption1, .bold)
}
let iconButton = IconButton(style: customStyle)
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 |
Type |
Description |
|---|---|---|
|
accessibilityTraits |
UIAccessibilityTraits |
The accessibilityTraits is automatically set to .button |
|
accessibilityLabel |
String? |
The accessibilityLabel describes the button action for VoiceOver |
|
accessibilityHint |
String? |
The accessibilityHint describes the result of activating the button |
Best practices
- Use descriptive titles for better accessibility.
- Set custom accessibilityLabel for icon-only buttons.
- Set accessibilityHint to describe the action result.
iconButton.title = "Add to favorites"
iconButton.button.accessibilityLabel = "Add item to favorites list"
iconButton.accessibilityHint = "Double tap to add this item to your favorites"
Dependencies
- External dependencies: None
- Internal dependencies: Button, DesignSystem.shared.styles
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
Tokens are defined in defaultTokens.json, which is integrated in the bundle of the framework, and can be customized by providing your own theme JSON file.
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.icon-button.default.background |
{theme.color.background.brand} |
|
Background (pressed) |
theme.color.icon-button.pressed.background |
{theme.color.background.brand-pressed} |
|
Foreground |
theme.color.icon-button.default.foreground |
{theme.color.on-background.brand} |
Semantic tokens
These tokens are accessed via the public DesignSystem.shared API.
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors.foreground.brand |
Brand color for the button |
|
Colors |
Theme.colors.foreground.disabled |
Disabled state color |
|
Typography |
DesignSystem.shared.fonts.preferredFont(.subheadline, .semibold) |
Label font |
|
Spacing |
DesignSystem.shared.spacer.sm |
Stack spacing |
|
Styles |
DesignSystem.shared.styles.primaryIconButton |
Primary icon button style |
|
Styles |
DesignSystem.shared.styles.dangerIconButton |
Danger icon button style |