Leaderboards

Browse Central Hub leaderboard rankings, track the signed-in user's rank, and paginate through additional results.

#Loading a Leaderboard

Use CentralHubLeaderboardProvider to load rankings for a specific category and timeframe.

The provider state includes:

loaded entries,
the current user's userRank,
loadingStatus for the initial request,
previousPageLoadingStatus for pagination, and
paging metadata such as allDataLoaded and currentPage.

kotlin

class LeaderboardViewModel : ViewModel(), KoinComponent {
    private val leaderboardProvider: CentralHubLeaderboardProvider = get()
    val state = leaderboardProvider.state

    fun loadFollowersWeeklyLeaderboard() {
        viewModelScope.launch {
            leaderboardProvider.loadLeaderboard(
                category = LeaderboardCategoryType.FOLLOWERS,
                timeframe = LeaderboardTimeframeType.WEEKLY,
            )
        }
    }

    override fun onCleared() {
        super.onCleared()
        leaderboardProvider.clear()
    }
}

kotlin

@Composable
fun LeaderboardScreen(
    vm: LeaderboardViewModel = viewModel(),
) {
    val state by vm.state.collectAsStateWithLifecycle()

    LaunchedEffect(Unit) {
        vm.loadFollowersWeeklyLeaderboard()
    }

    when (state.loadingStatus) {
        LoadingStatus.LOADING,
        LoadingStatus.INITIAL,
        -> CircularProgressIndicator()

        LoadingStatus.ERROR -> Text("Failed to load leaderboard")
        LoadingStatus.IDLE -> LazyColumn {
            items(state.entries) { entry ->
                Text(text = "#${entry.rank} ${entry.user.displayName} · ${entry.count}")
            }
        }
    }
}

#Loading More Results

Call loadMoreLeaderboard() to fetch the next page for the most recently loaded category and timeframe.

Use these fields to drive your pagination UI:

previousPageLoadingStatus
allDataLoaded
currentPage

tip

Disable your load-more UI while previousPageLoadingStatus is LOADING or when allDataLoaded is true.

kotlin

fun loadNextPage() {
    viewModelScope.launch {
        leaderboardProvider.loadMoreLeaderboard()
    }
}

kotlin

val canLoadMore =
    state.previousPageLoadingStatus != LoadingStatus.LOADING &&
        !state.allDataLoaded

Button(
    onClick = vm::loadNextPage,
    enabled = canLoadMore,
) {
    Text(
        when {
            state.previousPageLoadingStatus == LoadingStatus.LOADING -> "Loading..."
            state.allDataLoaded -> "All data loaded"
            else -> "Load more"
        }
    )
}

#State Behavior

During the first request:

loadingStatus moves from INITIAL to LOADING.
entries are replaced with the new first page.
currentPage resets to 0.
userRank is populated when that request succeeds.

During pagination:

previousPageLoadingStatus moves to LOADING.
new entries are appended to the existing list.
currentPage advances after success.
allDataLoaded becomes true when there are no more items to fetch.

info

If you keep the provider alive across multiple screens, call clear() when you want a fresh leaderboard session.

#Choosing Categories and Timeframes

#Categories

FOLLOWERS
POPULAR_BETS
BET_COMMENTS

#Timeframes

DAILY
WEEKLY
MONTHLY
ALL_TIME

#Data Models

#LeaderboardState

kotlin

data class LeaderboardState(
    val entries: List<LeaderboardEntry>,
    val userRank: UserLeaderboardRank?,
    val loadingStatus: LoadingStatus,
    val previousPageLoadingStatus: LoadingStatus,
    val allDataLoaded: Boolean,
    val currentPage: Int,
)

#LeaderboardEntry

kotlin

data class LeaderboardEntry(
    val rank: Int,
    val user: User,
    val count: Int,
)

#UserLeaderboardRank

kotlin

data class UserLeaderboardRank(
    val rank: Int,
    val score: Int,
    val totalUsers: Int,
)

Central Hub Overview - Main Central Hub feature documentation.
Onboarding - Show onboarding only to first-time users.
User Profiles - Load user profile data for ranked users.
Social Features - Work with follow relationships and social metrics.

Browse Central Hub leaderboard rankings, track the signed-in user's rank, and paginate through additional results.

#Loading a Leaderboard

Use CentralHubLeaderboardProvider to load rankings for a specific category and timeframe.

The provider state includes:

loaded entries,
the current user's userRank,
loadingStatus for the initial request,
previousPageLoadingStatus for pagination, and
paging metadata such as allDataLoaded and currentPage.

kotlin

class LeaderboardViewModel : ViewModel(), KoinComponent {
    private val leaderboardProvider: CentralHubLeaderboardProvider = get()
    val state = leaderboardProvider.state

    fun loadFollowersWeeklyLeaderboard() {
        viewModelScope.launch {
            leaderboardProvider.loadLeaderboard(
                category = LeaderboardCategoryType.FOLLOWERS,
                timeframe = LeaderboardTimeframeType.WEEKLY,
            )
        }
    }

    override fun onCleared() {
        super.onCleared()
        leaderboardProvider.clear()
    }
}

kotlin

@Composable
fun LeaderboardScreen(
    vm: LeaderboardViewModel = viewModel(),
) {
    val state by vm.state.collectAsStateWithLifecycle()

    LaunchedEffect(Unit) {
        vm.loadFollowersWeeklyLeaderboard()
    }

    when (state.loadingStatus) {
        LoadingStatus.LOADING,
        LoadingStatus.INITIAL,
        -> CircularProgressIndicator()

        LoadingStatus.ERROR -> Text("Failed to load leaderboard")
        LoadingStatus.IDLE -> LazyColumn {
            items(state.entries) { entry ->
                Text(text = "#${entry.rank} ${entry.user.displayName} · ${entry.count}")
            }
        }
    }
}

#Loading More Results

Call loadMoreLeaderboard() to fetch the next page for the most recently loaded category and timeframe.

Use these fields to drive your pagination UI:

previousPageLoadingStatus
allDataLoaded
currentPage

tip

Disable your load-more UI while previousPageLoadingStatus is LOADING or when allDataLoaded is true.

kotlin

fun loadNextPage() {
    viewModelScope.launch {
        leaderboardProvider.loadMoreLeaderboard()
    }
}

kotlin

val canLoadMore =
    state.previousPageLoadingStatus != LoadingStatus.LOADING &&
        !state.allDataLoaded

Button(
    onClick = vm::loadNextPage,
    enabled = canLoadMore,
) {
    Text(
        when {
            state.previousPageLoadingStatus == LoadingStatus.LOADING -> "Loading..."
            state.allDataLoaded -> "All data loaded"
            else -> "Load more"
        }
    )
}

#State Behavior

During the first request:

loadingStatus moves from INITIAL to LOADING.
entries are replaced with the new first page.
currentPage resets to 0.
userRank is populated when that request succeeds.

During pagination:

previousPageLoadingStatus moves to LOADING.
new entries are appended to the existing list.
currentPage advances after success.
allDataLoaded becomes true when there are no more items to fetch.

info

If you keep the provider alive across multiple screens, call clear() when you want a fresh leaderboard session.

#Choosing Categories and Timeframes

#Categories

FOLLOWERS
POPULAR_BETS
BET_COMMENTS

#Timeframes

DAILY
WEEKLY
MONTHLY
ALL_TIME

#Data Models

#LeaderboardState

kotlin

data class LeaderboardState(
    val entries: List<LeaderboardEntry>,
    val userRank: UserLeaderboardRank?,
    val loadingStatus: LoadingStatus,
    val previousPageLoadingStatus: LoadingStatus,
    val allDataLoaded: Boolean,
    val currentPage: Int,
)

#LeaderboardEntry

kotlin

data class LeaderboardEntry(
    val rank: Int,
    val user: User,
    val count: Int,
)

#UserLeaderboardRank

kotlin

data class UserLeaderboardRank(
    val rank: Int,
    val score: Int,
    val totalUsers: Int,
)

Central Hub Overview - Main Central Hub feature documentation.
Onboarding - Show onboarding only to first-time users.
User Profiles - Load user profile data for ranked users.
Social Features - Work with follow relationships and social metrics.

#Loading a Leaderboard

#Loading More Results

#State Behavior

#Choosing Categories and Timeframes

#Categories

#Timeframes

#Data Models

#LeaderboardState

#LeaderboardEntry

#UserLeaderboardRank

#Related Topics

Leaderboards

#Loading a Leaderboard

#Loading More Results

#State Behavior

#Choosing Categories and Timeframes

#Categories

#Timeframes

#Data Models

#LeaderboardState

#LeaderboardEntry

#UserLeaderboardRank

#Related Topics