X

useGithubProfile

PreviousNext

Fetch GitHub profile information and contribution data for a specific user.

useGithubProfile is a composable that provides a simple way to retrieve GitHub profile details (like avatar, bio, followers) and contribution history. It uses @vueuse/core under the hood for efficient fetching and reactivity.

Installation

pnpm dlx sulaf@latest add use-github-profile

Usage

<script setup lang="ts">
import { ref } from 'vue'
import { useGithubProfile } from '#imports'

const username = ref('octocat') // Default username

const { profile, totalContributions, isLoadingProfile, isProfileError } = useGithubProfile(username)
</script>

<template>
  <div class="flex flex-col gap-4">
    <Input v-model="username" placeholder="Enter GitHub username" />

    <div v-if="isLoadingProfile">Loading profile for {{ username }}...</div>

    <div v-else-if="isProfileError" class="text-red-500">
      Error fetching profile for {{ username }}. Please check the username.
    </div>

    <div v-else-if="profile">
      <img :src="profile.avatar_url" :alt="profile.name || profile.login" class="w-16 h-16 rounded-full" />
      <h1>{{ profile.name || profile.login }}</h1>
      <p>@{{ profile.login }}</p>
      <p v-if="profile.bio">{{ profile.bio }}</p>
      <p>Followers: {{ profile.followers }}</p>
      <p>Total Contributions (last year): {{ totalContributions }}</p>
    </div>
  </div>
</template>

API Reference

Parameters

ParameterTypeDescription
usernameMaybeRefOrGetter<string | undefined>The GitHub username to fetch data for.
optionsUseGithubProfileOptionsOptional configuration. year accepts 'last', 'all', or a year number. endpoint is a custom contributions URL template that supports {username} and {year} placeholders (for example, https://example.com/{username}/contributions?year={year}).

Return Values

ValueTypeDescription
profileRef<GitHubProfile | null>The GitHub user profile data.
contributionDataRef<Record<string, number>>A map of dates (YYYY-MM-DD) to contribution counts.
totalContributionsRef<number>The total number of contributions in the range.
isLoadingProfileRef<boolean>Whether the profile request is in flight.
isLoadingContributionsRef<boolean>Whether the contributions request is in flight.
isProfileErrorRef<boolean>Whether the profile request failed.
isContributionsErrorRef<boolean>Whether the contributions request failed.

Interfaces

export interface GitHubProfile {
  login: string
  name: string | null
  avatar_url: string
  bio: string | null
  location: string | null
  blog: string | null
  company: string | null
  followers: number
  following: number
  public_repos: number
  public_gists: number
  twitter_username: string | null
  html_url: string
}

export interface GitHubContributionDay {
  date: string
  count?: number
  level?: number
  contributionCount?: number
  color?: string
  contributionLevel?: string
}

export interface GitHubContributionsResponse {
  contributions: GitHubContributionDay[] | GitHubContributionDay[][]
  total?: number | Record<string, number>
  totalContributions?: number
}

export interface UseGithubProfileOptions {
  year?: MaybeRefOrGetter<string | number | undefined>
  endpoint?: MaybeRefOrGetter<string | undefined>
}
ComposablesuseIsMac