GitHub Repository Widget

Show off your GitHub projects with style using this lightweight widget. It's built to make your repositories look great on any website, with rich metadata and smooth animations that bring your code to life.

Installation

To integrate the GitHub Repository Widget into your website, you have two options. This widget allows you to dynamically display your GitHub repositories with customizable styles and sorting options, enhancing the interactivity and visual appeal of your site.

Option 1: Install via npm

If you're using a build system or module bundler, you can install the widget using npm:

npm install repowidget

After installation, import and initialize the widget in your JavaScript code:

import { createRepoWidget } from 'repowidget';

createRepoWidget({
    username: 'your-github-username',
    containerId: 'my-repos'
});

Option 2: Include the Script Directly

Alternatively, you can include the widget's JavaScript file directly in your HTML. This method is suitable if you prefer not to use npm:

<!-- Add the container where you want the repositories to appear -->
<div id="my-repos"></div>

<!-- Include the RepoWidget script -->
<script src="https://www.repowidget.com/bundle.js"></script>

<!-- Initialize the widget -->
<script>
    createRepoWidget({
        username: 'your-github-username',
        containerId: 'my-repos'
    });
</script>

Configuration

RepoWidget is highly customizable through its configuration options. These options control everything from the data source to the visual presentation of your GitHub repositories.

Configuration Options

Basic Example

Here's a simple configuration to get started:

createRepoWidget({
    username: 'octocat',           // GitHub username
    containerId: 'my-repos',       // Container element ID
    maxRepos: 6,                   // Show only 6 repos
    sortBy: 'stars'                // Sort by stars
});

Advanced Example

Here's a more advanced configuration with custom styling:

createRepoWidget({
    username: 'octocat',
    containerId: 'my-repos',
    columns: {
        mobile: 1,
        tablet: 2,
        desktop: 4
    },
    cardStyles: {
        backgroundColor: '#f8f9fa',
        boxShadow: '0 4px 6px rgba(0,0,0,0.1)',
        borderRadius: '8px',
        border: '1px solid #e9ecef'
    },
    textStyles: {
        titleColor: '#212529',
        descriptionColor: '#495057',
        iconColor: '#6c757d'
    },
    scaleOnHover: 1.03,
    sortBy: 'updated',
    maxRepos: 8
});

Features

RepoWidget is packed with features designed to make your GitHub repositories look great and provide a seamless user experience.

Styling

RepoWidget offers extensive styling options to ensure the widget matches your website's design. You can customize colors, shadows, borders, and more using the cardStyles and textStyles configuration options.

Card Styling

Use the cardStyles object to customize the appearance of repository cards:

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    cardStyles: {
        backgroundColor: '#ffffff',         // Card background color
        boxShadow: '5px 5px 15px #d1d1d1',  // Custom shadow
        borderRadius: '12px',               // Rounded corners
        border: '1px solid #e1e4e8',        // Border
        padding: '20px'                     // Inner spacing
    }
});

Text Styling

Use the textStyles object to customize text colors:

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    textStyles: {
        titleColor: '#2d3748',           // Repository name color
        descriptionColor: '#4a5568',     // Description text color
        iconColor: '#718096'             // Icon color (for stars, forks)
    }
});

Hover Effects

Control the hover effect using the scaleOnHover option:

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    scaleOnHover: 1.05,  // Cards grow by 5% on hover
    // Use 0 or false to disable hover effect:
    // scaleOnHover: 0
});

Styling Examples

Here are some preset styling examples you can use or modify:

Neumorphic Style

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    cardStyles: {
        background: 'linear-gradient(145deg, #ffffff, #f0f0f0)',
        boxShadow: '5px 5px 15px #d1d1d1, -5px -5px 15px #ffffff',
        borderRadius: '16px',
        border: 'none'
    },
    textStyles: {
        titleColor: '#2d3748',
        descriptionColor: '#4a5568',
        iconColor: '#718096'
    }
});

Flat Design

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    cardStyles: {
        backgroundColor: '#f7fafc',
        boxShadow: 'none',
        borderRadius: '4px',
        border: '1px solid #e2e8f0'
    },
    textStyles: {
        titleColor: '#1a202c',
        descriptionColor: '#4a5568',
        iconColor: '#a0aec0'
    },
    scaleOnHover: 0 // Disable hover effect
});

Dark Mode

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    cardStyles: {
        backgroundColor: '#2d3748',
        boxShadow: '0 4px 6px rgba(0,0,0,0.2)',
        borderRadius: '8px',
        border: '1px solid #4a5568'
    },
    textStyles: {
        titleColor: '#f7fafc',
        descriptionColor: '#e2e8f0',
        iconColor: '#a0aec0'
    }
});

Sorting Options

RepoWidget provides flexible sorting capabilities through the sortBy parameter, allowing you to present your repositories in the order that best highlights your work.

Available Sorting Methods

Sorting Examples

Here are examples of different sorting configurations:

Sort by Stars (Default)

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    sortBy: 'stars'
});

Show Most Forked Repositories

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    sortBy: 'forks',
    maxRepos: 6  // Limit to top 6 most forked repos
});

Alphabetical Sorting

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    sortBy: 'name'
});

Recently Updated Projects

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    sortBy: 'updated',
    maxRepos: 10  // Show top 10 most recently updated repos
});

Responsive Design

RepoWidget is built with responsiveness in mind, automatically adapting to different screen sizes to provide the optimal viewing experience across devices from mobile phones to large desktop monitors.

Configuring Columns for Different Devices

Use the columns object to specify the number of cards to display per row on different screen sizes:

createRepoWidget({
    username: 'github-username',
    containerId: 'my-repos',
    columns: {
        mobile: 1,   // 1 column on phones (< 640px)
        tablet: 2,   // 2 columns on tablets (640px - 1023px)
        desktop: 4   // 4 columns on desktop (≥ 1024px)
    }
});

Breakpoints

The widget uses the following breakpoints for responsive behavior:

• Mobile: < 640px
• Tablet: 640px - 1023px
• Desktop: ≥ 1024px

Examples for Different Layouts

Minimal Layout (Good for Sidebars)

createRepoWidget({
    username: 'github-username',
    containerId: 'sidebar-repos',
    columns: {
        mobile: 1,
        tablet: 1,
        desktop: 1
    },
    maxRepos: 3
});

Standard Layout

createRepoWidget({
    username: 'github-username',
    containerId: 'main-repos',
    columns: {
        mobile: 1,
        tablet: 2,
        desktop: 3
    }
});

Gallery Layout

createRepoWidget({
    username: 'github-username',
    containerId: 'gallery-repos',
    columns: {
        mobile: 1,
        tablet: 3,
        desktop: 5
    },
    maxRepos: 10
});

Interactive Demo

Try out different configurations for the GitHub Repository Widget below. Use the settings panel to customize the appearance and behavior of the widget.

Contributing

We welcome contributions from developers of all skill levels. Whether you're fixing bugs, adding features, or improving documentation - your help makes this widget better.

Quick Start Guide

1. Fork the repository
2. Clone your forked repository
3. Create a new branch for your feature or fix
4. Make your changes and commit them
5. Push your branch to your forked repository
6. Open a Pull Request