Skip to main content

Scott Nath Frontend Architect

Scott Nath's picture
GitHubdev.toLinkedInMastodon
Header image for article 'GitHub Profile Components as Native Web Components'

GitHub Profile Components as Native Web Components

Discover native web components that showcase GitHub profiles and repositories within the profile-components library.


Discover native web components that showcase GitHub profiles and repositories within the profile-components library.

GitHub profile native web components, which show a user and repositories, are included in the profile-components library. These are native web components, and can be used in any HTML page, framework-based site, or wherever you can use HTML. You can access them via unpkg.com or include the NPM module in your project.

Table of contents

tl;dr

install via npm:

npm i profile-components

use via unpkg.com:

<!-- add to HEAD -->
<script 
  type="module" 
  src="https://unpkg.com/profile-components-blahg/dist/github-user.js">
</script>

<!-- shows a GitHub profile with fetched content for user `scottnath` -->
<github-user username="scottnath" fetch="true"></github-user>
<!-- and a way to present repositories -->
<script 
  type="module" 
  src="https://unpkg.com/profile-components-blahg/dist/github-repository.js">
</script>

<!-- shows a GitHub repository with fetched content for repo `scottnath/profile-components` -->
<github-repository 
  full_name="scottnath/profile-components"
  fetch="true"></github-repository>

What are the GitHub profile components?

  • 100% native web components
  • Zero dependencies
  • Fetch profile and repository data from the GitHub API
  • No api key required
  • Present GitHub content as a profile widget
  • Styled using GitHub’s CSS style variables from Primer
  • Released in the profile-components library

Includes two components: user and repository

There are two components for GitHub (so far.)

GitHub repository

The repository web component displays details about a GitHub repository.

GitHub popular repo web component
GitHub popular repo web component
GitHub new repository web componen
GitHub new repository web component

GitHub user

The user web component displays details about a GitHub user, it may include a list of repositories. If repositories are included, the UI for a repository comes from the repository web component.

GitHub user web component
GitHub user web component
GitHub user with repositories
GitHub user with repositories

How to use the GitHub profile components

These components can be used on any HTML page - whether built via framework or just plain HTML. They are available via unpkg.com or you can add the NPM module to your project.

Using the unpkg distribution for a User

  1. Add the script tag to your HTML page’s HEAD:

    <!-- add to HEAD -->
    <script
      type="module" 
      src="https://unpkg.com/profile-components/dist/github-user.js">
    </script>
    
  2. Add the component to your HTML page’s BODY:

    <!-- shows a user's profile -->
    <github-user username="scottnath" fetch="true"></github-user>
    

    GitHub user with fetched content

  3. Include a list of repositories with the profile

    <github-user
      username="scottnath"
      fetch="true"
      repos='["scottnath/profile-components", "storydocker/storydocker"]'
    ></github-user>
    

    GitHub user with fetched content

  4. Write your own content instead of fetching from GitHub:

    <github-user
      username="scottnath"
      name="Meowy McMeowerstein"
      bio="Spending time purring and sleepin"
      followers="500000"
      following="2980"
      avatar_url="/MY_LOCAL_AVATAR_IMAGE.png"
      repos='[{
        "full_name":"scottnath/profile-components",
        "description":"Cool thing, does stuff",
        "language":"HTML"
      }]'
    ></github-user>
    

    GitHub user with user-derived content

Using the unpkg distribution for a Repository

  1. Add the repository script tag to your HTML page’s HEAD:

    <!-- add to HEAD -->
    <script
      type="module" 
      src="https://unpkg.com/profile-components/dist/github-repository.js">
    </script>
    
  2. Add the component to your HTML page’s BODY:

    <!-- shows a repository's information -->
    <github-repository 
      full_name="freeCodeCamp/freeCodeCamp" 
      fetch="true"></github-repository>
    

    GitHub repository with fetched content

  3. Add a theme to the repository component:

    <!-- shows a repository's information -->
    <github-repository 
      full_name="freeCodeCamp/freeCodeCamp" 
      fetch="true"
      theme="dark"></github-repository>
    

    GitHub repository with a theme

  4. Write your own content instead of fetching from GitHub:

    <github-repository 
      full_name="just-another/c-plus-plus-repo"
      language="C++"
      stargazers_count="123"
      forks_count="456"
      subscribers_count="789"
      description="This is meow meow."></github-repository>
    

    GitHub repository with local content

Server Side Rendering (Astro example)

Because these components were built with separate HTML, CSS, and JS files, you can use those pieces to generate HTML on the server. This example is what I did to make an Astro component for scottnath.com.

// GitHubUser.astro
---
import github from 'profile-components/github-utils';
const user = github.user;

const repos = JSON.stringify(['scottnath/profile-components', 'storydocker/storydocker']);
const userContent = await user.generateContent({
  login: 'scottnath',
  // a local profile image helps performance
  avatar_url: '/scott-nath-profile-pic.jpeg',
  repos
},true);
let userHTML = '<style>' + user.styles + '</style>';
userHTML += user.html(userContent);
---

<github-user>
  <template shadowrootmode="open" set:html={userHTML}>
  </template>
</github-user>

Where do the styles come from?

The best way to have the look n feel of an external site is to integrate their design language as much as possible. The GitHub components use the same source for styles as GitHub itself, the Primer Design System.

Primer Design System

https://primer.style/design/

Primer is a set of guidelines, principles, and patterns for designing and building UI at GitHub.

Primer is the source for all of GitHub’s root UI foundations (color text, and border-styles), iconography and basic UI patterns. The primer.style site is a massive resource for details about Primer and it’s use by GitHub, so check that out if you have more Primer-specific questions.

Color themes

GitHub (via Primer) has two sets of themes, light and dark, and each set contains a few variations. Check out Primer’s Storybook docs for colors to play around with the colors and see the different themes.

  • light: ‘Light’
  • light_colorblind: ‘Light Protanopia & Deuteranopia’
  • light_tritanopia: ‘Light Tritanopia’
  • light_high_contrast: ‘Light High Contrast’
  • dark: ‘Dark’
  • dark_dimmed: ‘Dark Dimmed’
  • dark_colorblind: ‘Dark Protanopia & Deuteranopia’
  • dark_tritanopia: ‘Dark Tritanopia’
  • dark_high_contrast: ‘Dark High Contrast’

Primatives and iconography

These components are styled with variables generated from Primer’s npm packages.

Auto-captured styles

CSS variables and svg icons are pulled from Primer’s npm packages. The generated variables are used to style the components. To make the styles easy to update when Primer makes changes, there is a suite of functions which pull the CSS variables and icons from Primer’s NPM packages. The functions are detailed in this README about the Primer-utilities on profile-components.