Configuration

This page explains how to configure the GitHub Bubble Chart using URL parameters or a custom JSON file. You can customize the chart appearance, data source, and theme to suit your needs.

API URL Parameters

You can customize the chart directly via URL parameters. Below are the available options:

Parameter	Type	Default Value	Description
username	string	-	GitHub username (required)
mode	string	top-langs	Chart mode: top-langs or custom-config
config-path	string	-	Path to custom JSON config (if using custom-config mode)
config-branch	string	main	Branch where the config file is located
width	number	600	Chart width in pixels
height	number	400	Chart height in pixels
title	string	Most Used Languages	Chart title
title-size	string	24	Font size of the title
title-weight	string	bold	Font weight of the title
title-color	string	#000000	Title text color
title-align	string	center	Title alignment: left, center, right
legend	boolean	true	Show legend (true/false)
legend-align	string	center	Legend alignment: left, center, right
theme	string	default	Theme of the chart
langs-count	number	10	Number of languages displayed (1-20)
display-values	string	legend	Value display mode: all, legend, bubbles, none

Example Usage:

https://github-bubble-chart.vercel.app?username=octocat&width=800&height=600&langs-count=5

Important

When using mode=custom-config, you must also specify a config-path parameter pointing to your JSON configuration file in your GitHub repository. In this mode, all display options will be loaded from your configuration file, and URL parameters will be ignored except for username, mode, config-path, and config-branch.

Custom Configuration JSON

If you prefer more advanced customization, you can provide a JSON configuration file. This is useful for defining colors, text styles, layout options, and fully custom data.

Configuration Structure

The custom configuration follows this structure:

{
  "options": {
    // Chart display options
  },
  "data": [
    // Array of data items
  ]
}

Example JSON Configuration

{
  "options": {
    "width": 800,
    "height": 600,
    "displayValues": "legend",
    "title": {
      "text": "Custom Chart",
      "fontSize": "24px",
      "fontWeight": "bold",
      "color": "#000000",
      "align": "middle"
    },
    "legend": {
      "show": true,
      "align": "center"
    },
    "theme": "default"
  },
  "data": [
    { "name": "JavaScript", "value": 50, "color": "#f1e05a" },
    { "name": "TypeScript", "value": 30, "color": "#2b7489" },
    { "name": "Python", "value": 20, "color": "#3572A5" }
  ]
}

Available Configuration Options

Top-Level Options

Option	Type	Description
options	Options	Contains all chart display options
data	Array of BubbleData	Array of data items to display in the chart

Options Object

Option	Type	Default	Description
width	number	600	Chart width in pixels
height	number	400	Chart height in pixels
displayValues	string	"legend"	How values are displayed: "none", "all", "legend", or "bubbles"
title	TitleOptions		Configuration for the chart title
legend	LegendOptions		Configuration for the chart legend
theme	string or Object	"default"	Theme name or custom theme object

Title Options

Option	Type	Default	Description
text	string	"Most Used Languages"	Chart title text
fontSize	string	"24px"	Font size of the title
fontWeight	string	"bold"	Font weight of the title
color	string	"#000000"	Title text color
align	string	"middle"	Text alignment: "start", "middle", or "end"

Legend Options

Option	Type	Default	Description
show	boolean	true	Whether to show the legend
align	string	"center"	Legend alignment: "left", "center", or "right"

Data Item Structure

Property	Type	Description
name	string	Label for the data item
value	number	Numeric value (determines bubble size)
color	string	Color code for the bubble (e.g., "#ff0000")
icon	string (optional)	URL or base64-encoded image for the icon

Note

For the icon property, you can now use either:

• Direct image URLs (e.g., https://example.com/icon.png)
• Base64-encoded images (e.g., data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...)

Custom Theme Object

{
  "textColor": "#ffffff",
  "backgroundColor": "#121212",
  "border": {
    "color": "#333333",
    "width": 1,
    "rounded": true
  }
}

Applying a Custom Configuration

If you have a custom JSON file in your GitHub repository, you can load it using:

https://github-bubble-chart.vercel.app?username=octocat&mode=custom-config&config-path=config.json&config-branch=main

Example: Advanced Custom Configuration

Here's an example with all available options:

{
  "options": {
    "width": 900,
    "height": 700,
    "displayValues": "all",
    "title": {
      "text": "My Programming Languages",
      "fontSize": "28px",
      "fontWeight": "600",
      "color": "#2d333b",
      "align": "start"
    },
    "legend": {
      "show": true,
      "align": "right"
    },
    "theme": {
      "textColor": "#24292e",
      "backgroundColor": "#f6f8fa",
      "border": {
        "color": "#e1e4e8",
        "width": 2,
        "rounded": true
      }
    }
  },
  "data": [
    {
      "name": "JavaScript",
      "value": 65,
      "color": "#f1e05a",
      "icon": "https://cdn.example.com/js-icon.png" 
    },
    { 
      "name": "TypeScript", 
      "value": 42, 
      "color": "#2b7489",
      "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." 
    },
    { "name": "Rust", "value": 28, "color": "#dea584" },
    { "name": "Go", "value": 15, "color": "#00ADD8" }
  ]
}

You can see a real example of a custom configuration file here.

⏳ Performance Optimization Tips

For performance optimization, consider these strategies:

• Limit Data Size: Reduce the number of languages fetched using the langs-count parameter.