API Reference

Complete documentation for the RepoWidget API

Navigation

Overview

RepoWidget is a JavaScript library that allows you to display GitHub repositories on any website. It provides a simple API to customize the display of repositories with various styling and configuration options.

createRepoWidget(options)

Creates and initializes the repository widget with the specified options.

createRepoWidget(options: RepoWidgetOptions): void

Return Value

void - This function does not return a value.

Options Object

The RepoWidget accepts a configuration object with the following properties:

Property Type Default Description
username String Required — GitHub username to fetch repositories from
containerId String Required — ID of the HTML element where repositories will be displayed
columns Object {mobile: 1, tablet: 2, desktop: 3} Number of columns for different device widths
maxRepos Number Based on columns Maximum number of repositories to display
sortBy String "stars" Sort criteria: "stars", "forks", "size", "name", or "updated"
scaleOnHover Number 1.05 Scale factor for hover effect (set to 0 to disable)
cardStyles Object {} CSS styles for repository cards
textStyles Object {} CSS styles for text elements

Required Parameters

username

String Required

The GitHub username whose repositories will be displayed.

// Using a personal GitHub username
createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container"
});

// Using an organization GitHub username
createRepoWidget({
    username: "microsoft",
    containerId: "repo-container"
});

containerId

String Required

The ID of the HTML element where the repositories will be rendered. 

// HTML: 

createRepoWidget({
    username: "peterbenoit",
    containerId: "my-github-repos"
});

Styling Parameters

columns

Object

An object specifying the number of columns for different screen sizes.

mobile Number of columns on screens smaller than 640px
tablet Number of columns on screens between 640px and 1024px
desktop Number of columns on screens larger than 1024px 
createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container",
    columns: {
        mobile: 1,   // 1 column on mobile
        tablet: 2,   // 2 columns on tablet
        desktop: 4   // 4 columns on desktop
    }
});

cardStyles

Object

An object containing CSS properties for styling the repository cards.

You can use any valid CSS properties in camelCase format.

createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container",
    cardStyles: {
        backgroundColor: '#f8f9fa',
        borderRadius: '12px',
        boxShadow: '0 10px 15px rgba(0,0,0,0.05)',
        border: '1px solid #e1e4e8'
    }
});

textStyles

Object

An object with color options for different text elements.

titleColor Color for repository names
descriptionColor Color for repository descriptions
iconColor Color for icons (stars, forks)
sizeColor Color for the repository size text 
createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container",
    textStyles: {
        titleColor: '#212529',
        descriptionColor: '#495057',
        iconColor: '#6c757d',
        sizeColor: '#adb5bd'
    }
});

Behavior Parameters

maxRepos

Number

The maximum number of repositories to display.

// Display only the top 5 repositories
createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container",
    maxRepos: 5
});

sortBy

String

The criteria to sort repositories by. Options include:

  • "stars" - Sort by star count (default)
  • "forks" - Sort by fork count
  • "size" - Sort by repository size
  • "name" - Sort alphabetically by name
  • "updated" - Sort by last update date
// Sort repositories by most recently updated
createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container",
    sortBy: "updated"
});

scaleOnHover

Number

The scale factor for the hover effect. Set to 0 to disable.

// Increase hover effect
createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container",
    scaleOnHover: 1.1
});

// Disable hover effect
createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container",
    scaleOnHover: 0
});

Complete Examples

Basic Usage

// Basic configuration with just required parameters
createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container"
});

Fully Configured Widget

// Complete configuration with all options
createRepoWidget({
    // Required parameters
    username: "peterbenoit",
    containerId: "repo-container",

    // Layout configuration
    columns: {
        mobile: 1,
        tablet: 2,
        desktop: 3
    },

    // Content configuration
    maxRepos: 6,
    sortBy: "stars",

    // Visual effects
    scaleOnHover: 1.05,

    // Styling
    cardStyles: {
        backgroundColor: "#ffffff",
        borderRadius: "8px",
        boxShadow: "0 4px 6px rgba(0,0,0,0.1)",
        border: "1px solid #e1e4e8"
    },

    // Text styling
    textStyles: {
        titleColor: "#24292e",
        descriptionColor: "#586069",
        iconColor: "#6a737d",
        sizeColor: "#959da5"
    }
});

Dark Mode Version

// Dark theme configuration
createRepoWidget({
    username: "peterbenoit",
    containerId: "repo-container",
    columns: {
        mobile: 1,
        tablet: 2,
        desktop: 3
    },
    cardStyles: {
        backgroundColor: "#2d333b",
        borderRadius: "8px",
        boxShadow: "0 4px 6px rgba(0,0,0,0.3)"
    },
    textStyles: {
        titleColor: "#e6edf3",
        descriptionColor: "#adbac7",
        iconColor: "#768390",
        sizeColor: "#636e7b"
    }
});