Fluffy Contribution

A Vue 3 component library for displaying GitHub contribution graphs in your Vue projects.

Features

• Lightweight and easy to use
• Two rendering modes: Vue components (DOM) and Canvas (native drawing)
• Support for multiple time ranges (yearly, monthly, weekly)
• Customizable themes and styles
• Dark mode support
• Compatible with Vue 3 and TypeScript
• Personal access token authentication for GitHub API

Installation

npm install fluffy-contribution-core
# or
yarn add fluffy-contribution-core
# or
pnpm add fluffy-contribution-core

FluffyContribution (New)

The redesigned contribution graph component with two rendering modes.

Quick Start

Vue Component Mode (Default)

<template>
  <FluffyContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    renderer="vue"
    theme="primary"
    @select="handleSelect"
  />
</template>

<script setup lang="ts">
import { FluffyContribution } from 'fluffy-contribution-core'

const handleSelect = (item: { time: string; count: number }) => {
  console.log(`Selected: ${item.time} with ${item.count} contributions`)
}
</script>

Canvas Mode

<template>
  <FluffyContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    renderer="canvas"
    theme="primary"
  />
</template>

<script setup lang="ts">
import { FluffyContribution } from 'fluffy-contribution-core'
</script>

Lite Mode

<template>
  <FluffyContribution
    :contributions="myData"
    mode="lite"
    renderer="vue"
  />
</template>

FluffyContribution Props

Property	Type	Default	Description
renderer	'vue' | 'canvas'	'vue'	Rendering mode
mode	'lite' | 'full'	'full'	Display detail level
type	'yearly' | 'monthly' | 'weekly'	'yearly'	Time range
theme	'primary' | 'yellow' | 'red'	'primary'	Color theme
shape	'square' | 'circle'	'square'	Cell shape (Vue mode only)
username	string	''	GitHub username
personalToken	string	''	GitHub personal access token
contributions	ContributionDay[]	[]	Direct data injection (overrides fetch)
name	string	'Fluffy Contribution'	Header title
notice	string	''	Header notice link text
showTimeSwitch	boolean	true	Show time range switcher
border	boolean	true	Show border
borderColor	string	'#e5e5e5'	Border color
backgroundColor	string	'#ffffff'	Background color
darkMode	boolean	false	Enable dark mode

Events

Event	Payload	Description
select	{ time: string, count: number }	Emitted when a contribution item is clicked

Exposed Methods

Method	Description
refresh()	Manually re-fetch contribution data
currentType	Current time range type (reactive)

---

Legacy Components (BaContribution)

The original components (BaContribution, BaItem, BaTimeSwitch, BaTooltip) remain available and functional.

Full Usage

<template>
  <BaContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    mode="full"
    type="yearly"
    level="medium"
    theme="primary"
    name="My Contributions"
    notice="Check out my GitHub activity!"
    :border="true"
    border-color="#e1e4e8"
    background-color="#ffffff"
    :dark-mode="false"
    :show-time-switch="true"
    @select="handleSelect"
  />
</template>

<script setup lang="ts">
import { BaContribution } from 'fluffy-contribution-core'

const handleSelect = (item: { time: string; count: number }) => {
  console.log(`Selected: ${item.time} with ${item.count} contributions`)
}
</script>

Lite Mode

<template>
  <BaContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    mode="lite"
    type="monthly"
    level="low"
  />
</template>

<script setup lang="ts">
import { BaContribution } from 'fluffy-contribution-core'
</script>

BaContribution Props

Property	Type	Default	Description
username	string	-	GitHub username (required)
personalToken	string	-	GitHub personal access token (required)
mode	'lite' | 'full'	-	Display mode: lite for simple view, full for detailed view
type	'yearly' | 'monthly' | 'weekly'	-	Time range for contribution data
level	'none' | 'low' | 'medium' | 'high'	-	Contribution level filter
theme	'primary' | 'yellow' | 'red' | ''	-	Color theme for contribution items
name	string	-	Display name for the contribution graph
notice	string	-	Notice message to display
border	boolean	-	Whether to show border
borderColor	string	-	Border color (CSS color value)
backgroundColor	string	-	Background color (CSS color value)
darkMode	boolean	-	Enable dark mode
showTimeSwitch	boolean	-	Show time range switcher

BaContribution Events

Event	Payload	Description
select	{ time: string, count: number }	Emitted when a contribution item is selected

Individual Item Usage

<template>
  <BaItem
    shape="circle"
    theme="primary"
    time="2024-01-15"
    :count="5"
    content="5 contributions"
    @toggle="handleToggle"
  />
</template>

<script setup lang="ts">
import { BaItem } from 'fluffy-contribution-core'

const handleToggle = (item: { time: string; count: number }) => {
  console.log(`Toggled: ${item.time}`)
}
</script>

BaItem Props

Property	Type	Default	Description
shape	'circle' | 'square'	-	Shape of the contribution item
theme	'primary' | 'yellow' | 'red' | ''	-	Color theme
time	string	-	Time label (e.g., date)
count	number	-	Number of contributions
content	string	-	Tooltip content (optional)

BaItem Events

Event	Payload	Description
toggle	{ time: string, count: number }	Emitted when item is clicked

GitHub Personal Access Token

To use this component, you need a GitHub personal access token:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate a new token with public_repo scope
3. Use the token in the personalToken prop

Configuration Examples

Dark Mode

<template>
  <FluffyContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    :dark-mode="true"
    background-color="#0d1117"
    border-color="#30363d"
  />
</template>

Custom Theme

<template>
  <FluffyContribution
    username="your-github-username"
    personal-token="your-github-personal-token"
    theme="yellow"
    renderer="canvas"
  />
</template>

With Direct Data

<script setup lang="ts">
import { FluffyContribution, type ContributionDay } from 'fluffy-contribution-core'

const myData: ContributionDay[] = [
  { date: '2025-01-01', count: 5 },
  { date: '2025-01-02', count: 3 },
  // ...
]
</script>

<template>
  <FluffyContribution
    :contributions="myData"
    mode="lite"
    renderer="canvas"
  />
</template>

License

MIT

Author

Fluffy_CX

---

Made with ❤️ for Vue 3 community