DOCSEARCHbyAlgolia
Submit Docs

Cosmos

repository·master·Indexed 24 days ago

https://github.com/evgenyneu/cosmos

A star rating UI control for iOS and tvOS written in Swift. Cosmos allows developers to display star ratings and capture user input with high customizability, supporting integration via Swift Package Manager, CocoaPods, Carthage, or manual source addition. It provides a CosmosView that can be configured via Interface Builder or programmatically to adjust rating, text, fill modes, and custom star images.

Tokens
1.3K
Snippets
4
Records
5
Agent score
31%

What's inside Cosmos

  1. Use Cosmos in Storyboard

    master

    To use Cosmos via Interface Builder:

    1. Drag a View object from the Object Library into your storyboard.
    2. In the Identity Inspector, set the view's class to CosmosView. Set its module property to Cosmos (unless you added the source file manually).
    3. Customize the appearance (stars, colors, etc.) using the Attributes Inspector.

    Note: If stars do not appear in the storyboard, go to the Editor menu and select Refresh All Views.

    Positioning: Use Auto Layout constraints. The view's width and height are determined automatically based on its content (stars and text), so you do not need to set explicit width/height constraints.

  2. Install Cosmos

    master

    You can add Cosmos to your Xcode project using several methods:

    Swift Package Manager (Recommended)

    In Xcode 11+, select File > Packages > Add Package Dependency... and enter the URL: https://github.com/evgenyneu/Cosmos.git.

    CocoaPods

    Add the following to your Podfile and run pod install:

    use_frameworks!
target 'Your target name'
pod 'Cosmos', '~> 25.0'

    Carthage

    Add this to your Cartfile and run carthage update:

    github "evgenyneu/Cosmos" ~> 25.0

    Manual Source Addition

    Simply add the CosmosDistrib.swift file directly into your Xcode project.

    use_frameworks!
target 'Your target name'
pod 'Cosmos', '~> 25.0'

  3. Configure CosmosView settings

    master

    You can customize the behavior and appearance of a CosmosView by modifying its settings object.

    Common Configuration Options

    • updateOnTouch: Set to false to prevent the rating from changing when touched (useful for read-only displays).
    • fillMode: Determines how stars are filled. Options are .full, .half, and .precise.
    • starSize: The size of the stars.
    • starMargin: The distance between stars.
    • filledColor: The color of a filled star.
    • emptyBorderColor: The border color of an empty star.
    • filledBorderColor: The border color of a filled star.

    Supplying Custom Star Images

    You can replace the default star shapes with custom UIImage objects:

    cosmosView.settings.filledImage = UIImage(named: "GoldStarFilled")
cosmosView.settings.emptyImage = UIImage(named: "GoldStarEmpty")
    // Do not change rating when touched
cosmosView.settings.updateOnTouch = false

// Show only fully filled stars
cosmosView.settings.fillMode = .full

// Change the size of the stars
cosmosView.settings.starSize = 30

// Set the distance between stars
cosmosView.settings.starMargin = 5

// Set the color of a filled star
cosmosView.settings.filledColor = UIColor.orange

// Set the border color of an empty star
cosmosView.settings.emptyBorderColor = UIColor.orange

// Set the border color of a filled star
cosmosView.settings.filledBorderColor = UIColor.orange

// Set image for the filled star
cosmosView.settings.filledImage = UIImage(named: "GoldStarFilled")

// Set image for the empty star
cosmosView.settings.emptyImage = UIImage(named: "GoldStarEmpty")

  4. Fix Cosmos interaction in iOS 13+ modal screens

    master

    On iOS 13 and later, the system's pan gesture for closing modal screens can interfere with Cosmos's touch handling. To ensure Cosmos works correctly inside a modal, disable pan gestures in its settings:

    cosmosView.settings.disablePanGestures = true
    cosmosView.settings.disablePanGestures = true

  5. Control CosmosView via code

    master

    After importing Cosmos, you can interact with a CosmosView instance (e.g., via an @IBOutlet) to update its state or respond to user input.

    Updating State

    // Change the rating
cosmosView.rating = 4

// Change the accompanying text
cosmosView.text = "(123)"

    Handling User Input

    Use closures to respond to rating changes:

    • didTouchCosmos: Called continuously as the user moves their finger across the view (useful for real-time UI updates).
    • didFinishTouchingCosmos: Called when the user lifts their finger (useful for saving the final rating to a database or server).
    // Change the cosmos view rating
cosmosView.rating = 4

// Change the text
cosmosView.text = "(123)"

// Called when user finishes changing the rating by lifting the finger from the view.
cosmosView.didFinishTouchingCosmos = { rating in }

// A closure that is called when user changes the rating by touching the view.
cosmosView.didTouchCosmos = { rating in }