Create beautiful, customizable, extendable, animated checkboxes on iOS. Completely configurable through interface builder. It has several built in animations, custom value support, a mixed state, checkmark and radio styles, circular and rounded rectangle box shapes, as well as full color customization. See the demo app to play with all the features.
Table of Contents
- Getting Started
- Project Structure
- Project Details
Check out the demo app to change the properties of the checkbox and see the changes in real time.
enum: The possible animations for switching to and from the unchecked state.
Animation: The type of animation to preform when changing from the unchecked state to any other state.
NSTimeInterval: The duration of the animation that occurs when the checkbox switches states. The default is 0.3 seconds.
(Any): Returns either the
mixedValuedepending on the checkbox's state.
Any: The object to return from
valuewhen the checkbox is checked.
Any: The object to return from
valuewhen the checkbox is unchecked.
Any: The object to return from
valuewhen the checkbox is mixed.
enum: The possible states the check can be in.
unchecked— No check is shown.
checked— A checkmark is shown.
mixed— A dash is shown.
CheckState: The current state of the checkbox.
Bool): Change the check state with the option of animating the change.
Bool= false): Toggle the check state between
- MarkType: The possible shapes of the mark.
checkmark— The mark is a standard checkmark.
radio— The mark is a radio style fill.
- BoxType: The possible shapes of the box.
circle— The box is a circle.
square— The box is square with optional rounded corners.
- tintColor: The main color of the
Mixedstates for certain animations.
UIColor: The color of the box in the unselected state.
UIColor: The color of the checkmark or radio for certain animations. (Mostly animations with a fill style.)
CGFloat: The line width of the checkmark.
MarkType: The type of mark to display.
CGFloat: The line width of the box.
CGFloat: The corner radius of the box if the box type is
BoxType: The shape of the checkbox.
Bool: Wether or not to hide the box.
To see a working playground in action, run the workspace located at path
M13Checkbox Demo Playground/LaunchMe.xcworkspace. You may need to run the framework scheme and wait for Xcode to process the files, before the playground begins. Open the assistant editor for a live preview of the UI.
This is a great way to work on customizing the checkbox in code to suit your needs.
To see the checkbox working on a device, run the demo app included in
M13Checkbox.xcodeproj. The demo app walks through all the available features. You will need to run a
pod install in order to build the demo app.
The easiest way to install M13Checkbox is through CocoaPods. Simplify add the following to your podfile.
To install via Carthage, add the following to your cartfile:
Swift Package Manager
To install via Swift Package Manager, add the following as a dependency to your Package.swift file:
.Package(url: "firstname.lastname@example.org:Marxon13/M13Checkbox.git", versions: Version(2,2,0)..<Version(2,2,3)),
Another option is to copy the files in the "Sources" folder to your project.
Add a custom view to the storyboard and set its class to "M13Checkbox". Customize the available parameters in the attributes inspector as needed.
Note: A shim was added to add support for setting enum properties through interface builder. Just retrieve the integer value corresponding to the enum value needed, and enter that into the property in the attributes inspector.
Just initialize the checkbox like one would initialize a UIView, and add it as a subview to your view hierarchy.
let checkbox = M13Checkbox(frame: CGRect(x: 0.0, y: 0.0, width: 40.0, height: 40.0)) view.addSubview(checkbox)
The main interface for M13Checkbox is the
M13Checkbox class. It is a subclass of
UIControl and handles the configurable properties, as well as touch events.
M13Checkbox references an instance of
M13CheckboxController, which controls the appearance and animations of its layers. The controller passes a set of layers to the
M13Checkbox, which adds the layers to its layer hierarchy. The checkbox then asks the controller to perform the necessary animations on the layers to animate between states. Each animation type has its own subclass of
M13CheckboxController. To add an animation, subclass
M13CheckboxController, and add the animation type to the
Animation enum, supporting
AnimationStyle if applicable. Take a look at the existing controllers to see what variables and functions to override.
M13CheckboxController references an instance of
M13CheckboxAnimationGenerator, which generates the animations that will be applied to layers during state transitions. The base class contains animations that are shared between multiple animation styles. An animation can subclass
M13CheckboxAnimationGenerator to generate new animations specific to the animation type.
M13CheckboxManager references an instance of
M13CheckboxPathGenerator, which generates the paths that will be displayed by the layers. The base class contains paths that are shared between multiple animation styles, as well as some boilerplate code to determine which path to use. Some animations have a subclass of
M13CheckboxPathGenerator to add new paths specific to the animation type, or override existing paths to customize the look.
M13CheckboxPathGenerator calculates the positions of the points of the checkmark with more than just a basic scaled offset. This allows the checkmark to always look the same, not matter what size the checkbox is. The math contained in the
checkmarkLongArmEndPoint are a simplified version of a human readable solution. To see the math that went into creating these equations, check out the "Math.nb" or the "Math.pdf" in the "Other" folder.
A shim that gives the ability to set the enum values of
M13Checkbox in Interface Builder.
- iOS 8+
- Xcode 9.0+
- Swift 4.0
To try the Swift 4.2 version, use the branch
- Fix the animations between the checked and mixed states when the mark is a radio. When the circle is close to being flat, the left and right edges are not rounded, as well as render some artifacts.
- Add visual feedback for UIControl's selected state. So that when the checkbox is touched, it animates slightly towards the new state.
- Add support for interrupting animations mid-animation. So that if the checkbox is tapped multiple times in quick succession, it animates from the current values, instead of resetting the checkbox and restarting the animations. This might involve replacing CAAnimations with manually done animations using a CADisplayLink. Or the new UIViewPropertyAnimator.
- tvOS support.
- watchOS support.
- macOS support.
- Checkbox cells (Re-add label support)
- Checkbox groups (single / multiple selection)
M13Checkbox is avaiable under MIT Licence.