<!--
{
  "availability" : [
    "iOS: 4.1.0 -",
    "iPadOS: 4.1.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.8.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 3.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "GameKit",
  "identifier" : "/documentation/GameKit/GKLeaderboard",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "GameKit"
    ],
    "preciseIdentifier" : "c:objc(cs)GKLeaderboard"
  },
  "title" : "GKLeaderboard"
}
-->

# GKLeaderboard

A leaderboard for a game that Game Center stores.

```
class GKLeaderboard
```

## Overview

Leaderboards allow players to compare their scores against other players in your game. You configure a classic or recurring leaderboard in App Store Connect and then access the localized information for a leaderboard in your code using [`GKLeaderboard`](/documentation/GameKit/GKLeaderboard) objects.

A *classic leaderboard* is persistent, that is, the scores never reset unless you delete the leaderboard. A *recurring leaderboard* contains scores for a period of time useful for competitions and encouraging players to try for higher scores. You configure the duration, frequency, and delay between occurrences that Game Center uses to automatically restart the leaderboard in App Store Connect.

In your code, you use the identifier you set for the leaderboard in App Store Connect to submit scores or load leaderboards. Use the [`submitScore(_:context:player:leaderboardIDs:completionHandler:)`](/documentation/GameKit/GKLeaderboard/submitScore(_:context:player:leaderboardIDs:completionHandler:)) class method to submit a score to one or more leaderboards. Alternatively, load a recurring leaderboard using the [`loadLeaderboards(IDs:completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadLeaderboards(IDs:completionHandler:)) class method and then submit a score using the [`submitScore(_:context:player:completionHandler:)`](/documentation/GameKit/GKLeaderboard/submitScore(_:context:player:completionHandler:)) method. To learn more about recurring leaderboards, see [Creating recurring leaderboards](/documentation/GameKit/creating-recurring-leaderboards).

To retrieve information about all leaderboards in your game, use the [`loadLeaderboards(IDs:completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadLeaderboards(IDs:completionHandler:)) class method. To fetch the scores for a leaderboard, use the [`loadEntries(for:timeScope:range:completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadEntries(for:timeScope:range:completionHandler:)) or [`loadEntries(for:timeScope:completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadEntries(for:timeScope:completionHandler:)) method. Use the parameters of these methods to filter the scores to the player’s friends, a rank, and time period when the score occurs.

You must create leaderboard objects using one of the load methods above. If the request is successful, GameKit passes corresponding [`GKLeaderboard`](/documentation/GameKit/GKLeaderboard) objects to the handler. GameKit doesn’t load the images you add to App Store Connect when it loads the leaderboards. Use the [`loadImage(completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadImage(completionHandler:)) method to get the image for a leaderboard.

## Topics

### Accessing Identifier and Type Properties

[`baseLeaderboardID`](/documentation/GameKit/GKLeaderboard/baseLeaderboardID)

The ID that Game Center uses to identify this leaderboard.

[`title`](/documentation/GameKit/GKLeaderboard/title)

The localized title for the leaderboard.

[`type`](/documentation/GameKit/GKLeaderboard/type)

The type of leaderboard, classic or recurring.

[`LeaderboardType`](/documentation/GameKit/GKLeaderboard/LeaderboardType)

Specifies whether a leaderboard is recurring.

[`groupIdentifier`](/documentation/GameKit/GKLeaderboard/groupIdentifier)

The identifier for the group the leaderboard belongs to.

### Accessing Recurring Leaderboard Properties

[`startDate`](/documentation/GameKit/GKLeaderboard/startDate)

The date and time a recurring leaderboard occurrence starts accepting scores.

[`nextStartDate`](/documentation/GameKit/GKLeaderboard/nextStartDate)

The date and time the next recurring leaderboard occurrence starts accepting scores.

[`duration`](/documentation/GameKit/GKLeaderboard/duration)

The duration from the start date that a recurring leaderboard occurrence accepts scores.

### Loading Leaderboards

[`+  loadLeaderboardsWithIDs:completionHandler:`](/documentation/GameKit/GKLeaderboard/loadLeaderboards(IDs:completionHandler:))

Loads leaderboards for the specified leaderboard IDs that Game Center uses.

[`-  loadPreviousOccurrenceWithCompletionHandler:`](/documentation/GameKit/GKLeaderboard/loadPreviousOccurrence(completionHandler:))

Loads the previous recurring leaderboard occurrence that the player submits a score to.

### Loading Leaderboard Images

[`-  loadImageWithCompletionHandler:`](/documentation/GameKit/GKLeaderboard/loadImage(completionHandler:))

Loads the image for the leaderboard.

### Submitting Scores

[`+  submitScore:context:player:leaderboardIDs:completionHandler:`](/documentation/GameKit/GKLeaderboard/submitScore(_:context:player:leaderboardIDs:completionHandler:))

Submits a score to multiple leaderboards.

[`-  submitScore:context:player:completionHandler:`](/documentation/GameKit/GKLeaderboard/submitScore(_:context:player:completionHandler:))

Submits a score to the leaderboard.

### Loading Scores

[`-  loadEntriesForPlayerScope:timeScope:range:completionHandler:`](/documentation/GameKit/GKLeaderboard/loadEntries(for:timeScope:range:completionHandler:))

Returns the scores for the local player and other players for the specified type of player, time period, and ranks.

[`-  loadEntriesForPlayers:timeScope:completionHandler:`](/documentation/GameKit/GKLeaderboard/loadEntries(for:timeScope:completionHandler:))

Returns the scores for the local player and other players for the specified time period.

[`PlayerScope`](/documentation/GameKit/GKLeaderboard/PlayerScope-swift.enum)

Specifies the type of players for filtering data.

[`TimeScope`](/documentation/GameKit/GKLeaderboard/TimeScope-swift.enum)

Specifies the time period for filtering data.

[`Entry`](/documentation/GameKit/GKLeaderboard/Entry)

Information about a single score by a player on a leaderboard.

### Deprecated

[Deprecated symbols](/documentation/GameKit/gkleaderboard-deprecated-symbols)

Review unsupported symbols and their replacements.

## Relationships

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

### Conforms To

[`CVarArg`](/documentation/Swift/CVarArg)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`Equatable`](/documentation/Swift/Equatable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Hashable`](/documentation/Swift/Hashable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)