react-svg-tournament-bracket

Customizable tournament brackets for React

What's New in 1.4.0

• Added option to render a secondary final above the rest of the bracket using the secondaryFinal prop

Installation

npm install react-svg-tournament-bracket

Usage

Here's an example of basic usage with eight teams starting at the quarter final round:

import React from "react";
import TournamentBracket from "react-svg-tournament-bracket";

const MyBracket = () => {
  const matches = [
    {
      homeTeamName: "Team A",
      awayTeamName: "Team B",
      round: 1,
      matchNumber: 1,
    },
    {
      homeTeamName: "Team C",
      awayTeamName: "Team D",
      round: 1,
      matchNumber: 2,
    },
    {
      homeTeamName: "Team E",
      awayTeamName: "Team F",
      round: 1,
      matchNumber: 3,
    },
    {
      homeTeamName: "Team G",
      awayTeamName: "Team H",
      round: 1,
      matchNumber: 4,
    },
    {
      homeTeamName: "Winner Match 1",
      awayTeamName: "Winner Match 2",
      round: 2,
      matchNumber: 5,
    },
    {
      homeTeamName: "Winner Match 3",
      awayTeamName: "Winner Match 4",
      round: 2,
      matchNumber: 6,
    },
    {
      homeTeamName: "Winner Match 5",
      awayTeamName: "Winner Match 6",
      round: 3,
      matchNumber: 7,
    },
  ];

  return <TournamentBracket matches={matches} />;
};

The component can now handle uneven brackets using the dummyMatch property on the Match Object. The length of your matches array should stil be an exponentiation of 2 but set the dummyMatch property to true for matches where there are no teams. These matches will take up the space where the match would go, causing the bracket to display evenly.

See below for an example of this.

The Match Object

The matches prop must be an array of objects, with the following required properties:

• homeTeamName: string

• awayTeamName: string

  the name of the each team (required unless dummyMatch is set to true)

• round: integer

  round should start at 1 and increment by 1. Each subsequent round should have half the number of matches as the previous round to keep the bracket even. There should only be a single match in the final round.

• matchNumber: integer

  matchNumber should be unique within a round. It will be used to display the matches in order. matchNumber 1 will display directly above matchNumber 2 and it should be expected that the winners of those two matches will play each other in the next round.

There are also several optional properties which are used:

• dateTime: any

  this value is used in conjuction with the dateTimeFormatter prop to display text in between the two teams of a match. It is normal to put the date and time of the match here but this can be used for anything (stadium name, matchup record, etc)

• homeTeamAbbreviation: string

• awayTeamAbbreviation: string

  max 6 character abbreviation of the team name

• matchComplete: boolean

  if true the scores will be displayed next to each team name

• matchAccepted: boolean

  if true the winner of the match (calculated from homeTeamScore vs awayTeamScore with PKs as a tiebreaker) will display in bold

• homeTeamScore: integer

• awayTeamScore: integer

  the score of the each team. Can be displayed next to the team name on the bracket. Also used for bolding the winning team

• homeTeamPKs: integer

• awayTeamPKs: integer

  if the match was tied and a team won on PKs the winning team will be bolded

• homeTeamLogo: string (url location of image)

• awayTeamLogo: string (url location of image)

  if provided will display a small image next to the team name on the bracket. Must be the full path to the image.

• dummyMatch: boolean

if true then the match will not be displayed but the space will be filled with the background color. Use this property to create uneven brackets using placeholder matches.

• highlight: array || string

acceptable values are "home" "away" and "match". Use this property if you wish to highlight an element in an individual match. The checking used the include method so you can pass this as an array or string. Using "home" and/or "away" will highlight the corresponding team, while using "match" will highlight the link text in between the two teams. These values can be used in any combination. Use the highlightColor prop on the TournamentBracket to pick the colors of the highlighting.

Props

PropName	Description	Default Value	Example Values
matches	Array of Match Objects	none, prop is required	see basic usage example
emptyBracketComponent	component or text string that will display when matches is falsy or length is 0. Pass an empty string to display nothing	"There are no matches to display"	""
onSelectMatch	callback function called when clicking the match number or dateTime. Argument passed back is the match object	undefined	(match) => console.log(match)
onSelectTeam	callback function called when clicking an individual team. Arguments passed back are the match and a string 'home' or 'away' to represent which team was clicked	undefined	(match, team) => console.log(match, team)
orientation	display orientation of the bracket, either landscape or portrait	"landscape"	"portrait"
flipTeams	boolean, if true the teams will display away team on top	false	true
backgroundColor	hex or html color for the bracket background	"#fff"	"#831fe0"
textColor	hex or html color for text	"#000"	"#831fe0"
popColor	hex or html color for "pop" elements of the bracket, such as the box around the final match	"831fe0"	"red"
lineColor	hex or html color for the connecting lines between matches	"#000"	"blue"
dateTimeFormatter	function called on the value of match.dateTime to display in between the teams for each match. If undefined no date or time will display	undefined	(dateTime) => new Date(dateTime).toLocaleString()
displayMatchNumber	boolean, will the match number display in between the match. If neither the match number nor the dateTime are displayed the the match is no longer selectable	true	false
showFullTeamNames	boolean, the bracket will display the full team name if true, if false will display the value of homeTeamAbbreviation or awayTeamAbbreviation, or the first 6 letters of the full team name, capitalized. When hovered over the full team name will display	true	false
width	overall width of entire bracket	depends on orientation, for landscape: 1280, portrait: 500	750
height	overall height of entire bracket	720	500
matchHeight	height of each individual match in the bracket. Text size will scale up or down with this height. Although you can set this to any value it is recommended for best display to pick a size between 75 - 1000	100	75
matchKeyCreator	function to pull a key from each match to satisfy React mapping requirements	(match) => String(match.round) + String(match.matchNumber)	(match) => match._id
disableStrictBracketSizing	boolean, strict bracket sizing is enabled by default. This means that the number of matches in each round should be an exponentiation of 2, and each round should have half the number of matches as the previous round. It is suggested that you use dummy matches to fill in the gaps to meet this criteria, but the check can be disabled by setting this prop to true.	false	true
hidePKs	boolean, if true the home and away team PKs will not be shown on a complete match which is tied. Use this prop to keep your tiebreaker hidden while still enabling the winning team to display in bold	undefined	true
highlightColor	object: {backgroundColor: string, color: string}, used in conjunction with the highlight prop on the Match Object, to highlight elements of an individual match	{backgroundColor: "#831fe0", color: "fff"}	{backgroundColor: "red", color: "white"}
secondaryFinal	if you have a loser's/secondary bracket then it is likely that your bracket will need to have another final between the winner of the main bracket and the winner of the loser's bracket. This match can be displayed on a bracket using the secondaryFinal prop. This takes a regular Match Object, with an added field of "title", which will display above the rendered match. See complex examples for more information.	undefined	{homeTeamName: "Team A",awayTeamName: "Team B",title: "Secondary Final",}

More Complex Examples

Displaying bracket with score showing

Use the matchComplete and matchAccepted properties on each Match Object to display the scores on the brackets.

matchComplete = true will cause the score to display next to each team. If the score props is not included then 0 will display.

matchAccepted = true will cause the winning team (based on homeTeamScore vs awayTeamScore, with the PK tiebreaker) to display in bold. This prop can be used without the matchComplete prop to embolden the winning team while not displaying the score.

import React from "react";
import TournamentBracket from "react-svg-tournament-bracket";

const MyBracket = () => {
  const matches = [
    {
      homeTeamName: "Team A",
      awayTeamName: "Team B",
      round: 1,
      matchNumber: 1,
      homeTeamScore: 3,
      awayTeamScore: 2,
      matchComplete: true,
      matchAccepted: true,
      // this match will display the scores with Team A in bold
    },
    {
      homeTeamName: "Team C",
      awayTeamName: "Team D",
      round: 1,
      matchNumber: 2,
      homeTeamScore: 1,
      awayTeamScore: 1,
      homeTeamPKs: 1,
      awayTeamPKs: 3,
      matchComplete: true,
      // this match will display the scores (and the PK tiebreaker) but neither team will be in bold as matchAccepted is not included
    },
    {
      homeTeamName: "Team A",
      awayTeamName: "Team D",
      round: 2,
      matchNumber: 3,
      homeTeamScore: 1,
      awayTeamScore: 2,
      // this match will not display the score at all as matchComplete is not included
    },
  ];

  return (
    <TournamentBracket
      matches={matches}
      backgroundColor="#eeccff"
      popColor="blue"
    />
  );
};

Uneven bracket using dummyMatch property

This is how to display an uneven bracket with a lead in round. The entire quarter final round (round 1) needs to be included, but all the placeholder matches have the dummyMatch property set to true. The matchNumber property is only used to sort matches within each round, so they can be duplicated in the next round. So here we are able to number the placeholder matches for correct sorting while also keeping more logical match numbering for real matches on the bracket display.

import React from "react";
import TournamentBracket from "react-svg-tournament-bracket";

const MyBracket = () => {
  const matches = [
    {
      homeTeamName: "Team A",
      awayTeamName: "Team B",
      round: 1,
      matchNumber: 1,
    },
    {
      round: 1,
      matchNumber: 2,
      dummyMatch: true,
    },
    {
      round: 1,
      matchNumber: 3,
      dummyMatch: true,
    },
    {
      round: 1,
      matchNumber: 4,
      dummyMatch: true,
    },
    {
      homeTeamName: "Winner Match 1",
      awayTeamName: "Team C",
      round: 2,
      matchNumber: 2,
    },
    {
      homeTeamName: "Team D",
      awayTeamName: "Team E",
      round: 2,
      matchNumber: 3,
    },
    {
      homeTeamName: "Winner Match 2",
      awayTeamName: "Winner Match 3",
      round: 3,
      matchNumber: 4,
    },
  ];

  return (
    <TournamentBracket
      matches={matches}
      backgroundColor="#eeccff"
      popColor="blue"
    />
  );
};

Using match highlighting

Elements within an individual match can be highlighted. This could be used to indicate the winning team without using the score and accepted properties, or highlight an individual match.

import React from "react";
import TournamentBracket from "react-svg-tournament-bracket";

const MyBracket = () => {
  const matches = [
    {
      homeTeamName: "Winner Match 1",
      awayTeamName: "Team C",
      round: 1,
      matchNumber: 1,
      highlight: ["home", "away"], // both teams will be highlighted
    },
    {
      homeTeamName: "Team D",
      awayTeamName: "Team E",
      round: 1,
      matchNumber: 2,
      highlight: "home", // only the home team will be highlighted
    },
    {
      homeTeamName: "Winner Match 2",
      awayTeamName: "Winner Match 3",
      round: 2,
      matchNumber: 3,
      highlight: "match away", // the match link and the away team will be highlighted
    },
  ];

  return (
    <TournamentBracket
      matches={matches}
      backgroundColor="#eeccff"
      popColor="blue"
      highlightColor={{ backgroundColor: "red", color: "white" }} // the highlighted elements will display as white text on a red background
    />
  );
};

Using the secondaryFinal prop

In this scenario there is a loser's bracket (not displayed) where the winner of that bracket will be able to come back into the main bracket and compete for the championship. This match will be shown using the secondaryFinal prop by passing in a complete Match Object with the additional "title" property to display above the match.

import React from "react";
import TournamentBracket from "react-svg-tournament-bracket";

const MyBracket = () => {
  const matches = [
    {
      homeTeamName: "Team A",
      awayTeamName: "Team B",
      round: 1,
      matchNumber: 1,
      homeTeamScore: 1,
      awayTeamScore: 0,
      matchComplete: true,
      matchAccepted: true,
    },
    {
      homeTeamName: "Team C",
      awayTeamName: "Team D",
      round: 1,
      matchNumber: 2,
      homeTeamScore: 0,
      homeTeamPKs: 5,
      awayTeamScore: 0,
      awayTeamPKs: 4,
      matchComplete: true,
      matchAccepted: true,
    },
    {
      homeTeamName: "Team E",
      awayTeamName: "Team F",
      round: 1,
      matchNumber: 3,
      homeTeamScore: 1,
      awayTeamScore: 2,
      matchComplete: true,
      matchAccepted: true,
    },
    {
      homeTeamName: "Team G",
      awayTeamName: "Team H",
      round: 1,
      matchNumber: 4,
      homeTeamScore: 3,
      awayTeamScore: 0,
      matchComplete: true,
      matchAccepted: true,
    },
    {
      homeTeamName: "Team A",
      awayTeamName: "Team C",
      round: 2,
      matchNumber: 5,
    },
    {
      homeTeamName: "Team F",
      awayTeamName: "Team G",
      round: 2,
      matchNumber: 6,
    },
    {
      homeTeamName: "Winner Match 5",
      awayTeamName: "Winner Match 6",
      round: 3,
      matchNumber: 7,
    },
  ];

  return (
    <TournamentBracket
      matches={matches}
      backgroundColor="lightblue"
      popColor="yellow"
      secondaryFinal={{
        homeTeamName: "Winner Match 7",
        awayTeamName: "Winner Loser's Bracket",
        title: "Secondary Final",
      }}
    />
  );
};

Release Notes

1.4.0

• Added option to render a secondary final above the rest of the bracket using the secondaryFinal prop

1.3.0

• The matchHeight property now works as expected to expand the area each match takes up and the size of the text. Recommended values are between 75 - 1000
• You can now highlight elements of an individual match using the highlight property of the Match Object and the highlightColor prop.

1.2.0

• Dummy matches on lopsided landscape brackets will no longer take up space if the entire round on that side of the bracket is dummy matches. This will however cause the final to not display in the center of the bracket.
• hidePKs props allows you to use the home/awayTeamPKs prop on the Match Object as a tiebreaker to bold the winning team but keep it hidden on the bracket display.
• Added error checking to round lengths to ensure proper display. Can be disabled with disableStrictBracketSizing prop.
• Added error checking to teamName property on match object

1.1.1

• Package was not built before publishing, changes did not go into effect. Rebuilt package.

1.1.0

• Added dummyMatch property to Match Object allowing for uneven bracket display (see Complex Examples section).
• Removed unnecessary connecting lines between matches on larger brackets making for a cleaner look.

License

MIT