🌲🌲🌲 Beautiful Skill Tree

A small library to help get you implement beautiful, responsive, and satisfying skill trees into your React applications.

For every star Beautiful Skill Tree gets, £1 will be donated to Trees for Life. As cool as it is creating beautiful trees in your apps, it's even cooler doing so in real life!

Beautiful Skill Tree has currently raised £105 (+ Gift Aid) thanks to the lovely folk starring this repo.

Thanks to my friends, family, coworkers, and strangers in ensuring that it has been tested across a diverse range of people.

Tested across devices using Browserstack, thanks to their continued support for open source projects.

This package uses tsdx and np develop, build, package, and publish beautiful-skill-tree. I can't recommend either of them enough and they both make for an excellent TypeScript/JavaScript developer experience.

Table of Contents

1. Examples
2. Getting started
3. Motivation
4. API
5. Features
6. Contributing

Examples

• Calisthenics Progressions
• Borderlands Skill Tree
• Applying Skill Trees to Education/Business/Sports

Getting started

yarn add beautiful-skill-tree

The package exposes three components

SkillTree

SkillTreeGroup

SkillProvider

The

SkillTree

The

SkillTreeGroup

The

SkillProvider

For those that like their data typed, you can also import

SkillType

SkillGroupDataType

SkillThemeType

SavedDataType

Wrap your application like this:

import {
  SkillTreeGroup,
  SkillTree,
  SkillProvider,
  SkillType,
  SkillGroupDataType,
} from 'beautiful-skill-tree';

const data: SkillType[] = [];

  
    {({ skillCount }: SkillGroupDataType) => (
      
    )}
  
;

Or, if you are coding in ES6, here's the code:

import {
  SkillTreeGroup,
  SkillTree,
  SkillProvider,
  SkillType,
  SkillGroupDataType
} from 'beautiful-skill-tree';


const data = [];

  
    {({ skillCount }) => (
      
    })
    

Run your application's starting script and access localhost to find an empty skill tree. The skill tree will remain empty until data of type

Skill[]

Optional

SkillTree

collapsible

disabled

description

collapsible

disabled

description

Add the following data to your skill tree and see what happens:

const data: SkillType[] = [
  {
    id: 'hello-world',
    title: 'Hello World',
    tooltip: {
      content:
        'This node is the top most level, and will be unlocked, and ready to be clicked.',
    },
    children: [
      {
        id: 'hello-sun',
        title: 'Hello Sun',
        tooltip: {
          content:
            'This is a parent of the top node, and will locked while the parent isn’t in a selected state.',
        },
        children: [],
      },
      {
        id: 'hello-stars',
        title: 'Hello Stars',
        tooltip: {
          content:
            'This is the child of ‘Hello World and the sibling of ‘Hello Sun’. Notice how the app takes care of the layout automatically? That’s why this is called Beautiful Skill Tree and not just ‘Skill Tree’. (Also the npm namespace had already been taken for the latter so (flick hair emoji).',
        },
        children: [],
      },
    ],
  },
];

Go to your browser and you should see this:

Motivation

Is there anything more satisfying than the feeling of progression; improving at something you care deeply about? Not likely! Be it in video games, web development, or your physical capabilities, very little gives us a sense of pride and accomplishment than gaining new skills and using them. My motivation was to make skill trees that feel satisfying and fun to use.

Unfortunately there aren't any React packages that enable us developers to easily create skill trees in their applications. This is where Beautiful Skill Tree comes in. BST is a small package that allows you to easily create your own skill trees that look great across devices and screen sizes.

API

SkillTree

treeId:

string

[required]

title:

string

[required]

data:

SkillType

[required]

collapsible:

boolean

[optional]

closedByDefault

boolean

[optional]

disabled

boolean

[optional]

description:

string

[optional]

savedData:

SavedDataType

[optional]

handleSave:

(context: ContextStorage, treeId: string, skills: SkillType) => void

[optional]

handleNodeSelect:

(event: NodeSelectEvent) => void

[optional]

SkillTreeGroup

theme:

SkillThemeType

[optional]

children:

(treeData: SkillGroupDataType) => React.ReactNode

[required]

SkillProvider

SkillType

type SkillType[] = {
  id: string;
  title: string;
  optional?: boolean;
  tooltip: {
    content: React.ReactNode;
    direction?: 'top' | 'left' | 'right' | 'bottom', // top = default
  };
  icon?: string;
  children: SkillType[];
}

SkillGroupDataType

type SkillGroupData = {
  skillCount: SkillCount;
  selectedSkillCount: SkillCount;
  resetSkills: () => void;
  handleFilter: (query: string) => void;
};

type SkillCount = {
  optional: number;
  required: number;
};

SavedDataType

type SavedDataType = {
  [key: string]: {
    optional: boolean;
    nodeState: 'selected' | 'unlocked' | 'locked';
  };
};

NodeSelectEvent

type NodeSelectEvent = {
  key: string;
  state: 'selected' | 'unlocked' | 'locked';
};

Features

Filtering

The

handleFilter()

 handleFilter(e.target.value)}
  placeholder="Filter through trees..."
/>

The

closedByDefault

Custom Themes

It's likely that you're application won't look to hot with a dark blue/rainbow themed skill tree. Fortunately, a custom theme can be supplied to the

SkillTreeGroup

SkillThemeType

There are some gotcha related to some of my hacky CSS. Because I like me some gradients, to get the borders looking all swanky, i've had to use the

border-image

linear-gradient(
  to right,
  #ffffff 0%,
  #ffffff 100%
)

URL Navigation

As each

treeId

id

treeOne

treeTwo

Custom Saving

beautiful-skill-tree

• Creating simple skill trees
• Web apps that require no authentication
• Rapid prototyping

Saving to local storage is not great for:

• Data persistence across devices
• Web apps that require authentication
• Giving control to power users

Saving and loading works automatically, but it's possible pass in your own implementation, should you want to extend the save/loading capabilities, or if your application utilises authentication. The

SkillTree

savedData

handleSave

SavedDataType

handleSave

Storage

treeId

skills

// the state of the skill tree, as per my custom implementation
const savedData: SavedDataType = {
  'item-one': {
    optional: false,
    nodeState: 'unlocked',
  },
  'item-two': {
    optional: false,
    nodeState: 'locked',
  },
};

function handleSave(
  storage: ContextStorage,
  treeId: string,
  skills: SavedDataType
) {
  return storage.setItem(skills-${treeId}, JSON.stringify(skills));
}
const App = () => {
  return (
    
      
        {() => {
          return (
            
          );
        }}
      
    
  );
};

Keyboard only use

The tree is currently fully navigable using the keyboard. Pressing the tab button will cycle through the nodes, while pressing enter will select the focused node.

Contributing

contributing guidelines

Running locally

You'll need to clone the repo on your local machine and install the dependencies using

yarn

If you're using nvm, you can ran

nvm use

.nvmrc

git clone https://github.com/andrico1234/beautiful-skill-tree.git

cd ./beautiful-skill-tree

yarn:test

yarn

yarn start

If you're having issues with any of the steps above, then please open a ticket with any error logging the console outputs. If your local server is working without any issues then open up a new terminal window in the same directory and start the local example. Running the example will spin up a demo app on

localhost:1234

cd ./example

yarn

yarn start

access localhost:1234 in your browser.

Contributors

• Andrico Karoulla
• Juan Melendez