Cluster

Cluster can be integrated into your iOS project using either CocoaPods or Carthage.

CocoaPods Add the following to your Podfile:

pod "Cluster"

Carthage Add the following to your Cartfile:

github "efremidze/Cluster"

To display clusters on the map, you must implement the mapView(_:viewFor:) delegate method. When the annotation is a ClusterAnnotation, return an instance of ClusterAnnotationView (or a subclass).

For standard pins, return a regular MKAnnotationView (like MKPinAnnotationView).

extension ViewController: MKMapViewDelegate {
    func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? {
        if let annotation = annotation as? ClusterAnnotation {
            return CountClusterAnnotationView(annotation: annotation, reuseIdentifier: "cluster")
        } else {
            return MKPinAnnotationView(annotation: annotation, reuseIdentifier: "pin")
        }
    }
}

To remove an annotation, call manager.remove(annotation:).

Important: Annotations are not immediately removed from the map view. You must call reload(mapView:completionHandler:) to update the display. It is recommended to call reload() whenever you add or remove annotations, and specifically when the map region changes.

// Remove
manager.remove(annotation)

// Reload (typically in mapView(_:regionDidChangeAnimated:))
func mapView(_ mapView: MKMapView, regionDidChangeAnimated animated: Bool) {
    clusterManager.reload(mapView: mapView) { finished in
        // handle completion
    }
}

You can customize the look of clusters by subclassing ClusterAnnotationView and overriding the configure() method. This is useful for modifying properties like countLabel, layer.borderColor, or layer.cornerRadius.

class CountClusterAnnotationView: ClusterAnnotationView {
    override func configure() {
        super.configure()

        self.layer.cornerRadius = self.frame.width / 2
        self.layer.masksToBounds = true
        self.layer.borderColor = UIColor.white.cgColor
        self.layer.borderWidth = 1.5
    }
}

You can use the ClusterAnnotationStyle enum to define how an annotation appears. Supported styles include:

• .color(UIColor, radius: CGFloat): Displays the annotation as a circle.
• .image(UIImage?): Displays the annotation as an image.

When using styles, you must return a StyledClusterAnnotationView in your mapView(_:viewFor:) implementation.

let annotation = Annotation(coordinate: CLLocationCoordinate2D(latitude: 21.283921, longitude: -157.831661))
annotation.style = .color(color, radius: 25)
manager.add(annotation)

// In mapView(_:viewFor:)
if let annotation = annotation as? ClusterAnnotation {
    return StyledClusterAnnotationView(annotation: annotation, reuseIdentifier: identifier, style: style)
}

The ClusterManagerDelegate protocol allows you to control clustering logic and cell sizing via two methods:

• cellSize(for zoomLevel: Double) -> Double?: Returns the size of each cell on the grid for a specific zoom level.
• shouldClusterAnnotation(_ annotation: MKAnnotation) -> Bool: Returns a boolean indicating whether a specific annotation should be clustered.

To add annotations, ensure your object conforms to the MKAnnotation protocol. Use the add(annotation:) method on your ClusterManager instance.

let annotation = Annotation(coordinate: CLLocationCoordinate2D(latitude: 21.283921, longitude: -157.831661))
manager.add(annotation)

The ClusterManager class is the core component used to generate, manage, and display annotation clusters using a QuadTree method.

To start, initialize an instance of ClusterManager.

let clusterManager = ClusterManager()

The ClusterManager provides several properties to fine-tune clustering behavior: