react-dice-3d

Customizable 3D dice with individual and group logic features

Installation

Install with npm:

npm install react-dice-3d

Quick Start

Wrap your App or section of your app with the <DiceProvider> component:

import { DiceProvider } from "react-dice-3d";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <DiceProvider>
    <App />
  </DiceProvider>,
);

The component is required to manage the state and context for dice rolling throughout your app.

Import the Die component.

import { Die } from "./Die";

<Die onRoll={(value) => console.log(value)} />;

Usage

<Die>

A single die. Rolls on click by default.

Props

Controlling the Die

You have multiple options for triggering a die roll:

via props

• keyboardListeners roll die via keypress
• Roller gives you a programmatic roll function and returns an element to act as a roll controller.
• onClick allows you to augment the default behavior of the click roll by giving you the roll function to call after you implement your logic.

via hook

You can have programmatic access to a die via the useDie() hook by giving the die an id:

import {useDie} from "react-dice-3d";

const die = useDie("my-die");

<Die id="my-die" />
<button onClick={() => die.roll()}>Hook Roll</button>

useDie() returns two functions:

{
    roll: () => Promise<number>
    toggleFreeze: () => void
}

See <DiceGroup> section for more on toggleFreeze()

via ref

const dieRef = useRef(null);

<Die ref={dieRef} />
<button onClick={() => dieRef.current.roll()}>Ref Roll</button>

You get the same functions that you get from the useDie() hook:

{
    roll: () => Promise<number>;
    toggleFreeze: () => void;
}

<DiceGroup>

Groups dice for rolling and grouping results together.

The default behavior of clicking a die in a group is to freeze the result. If a die is frozen, it will not roll when the group rolls and it's value will be saved and used by the RollGroupResult on group roll.

Basic usage

All you need to do is import the component and give it a diceCount

import { DiceGroup } from "react-dice-3d";

<DiceGroup diceCount={3} useDefaultRoller />;

Props

RollGroupResult:

{
    values: number[];
    sum: number;
    groupings: Record<number, number>;
}

• values is an array of the individual die values
• sum is the sum of all values
• groupings is an object whose keys are the result of a roll the value is how many times that result appears.
  • Ex. a roll of 5, 5, 4, 3, 3 would give you a grouping of:
    • { 3: 2, 4: 1, 5: 2}

Controlling the DiceGroup

Like the Die component, you have several options for controlling the DiceGroup

via props

• keyboardListeners roll group via keypress
• Roller gives you a programmatic roll function and returns an element to act as a group roll controller.

via hook

You can have programmatic access to a dice group via the useDiceGroup() hook by giving the DiceGroup an id:

import {useDiceGroup} from "react-dice-3d";

const group = useDiceGroup(`my-group`);

<DiceGroup id={`my-group`} />
<button onClick={() => group.roll()}>Hook Roll</button>

via ref

const diceGroupRef = useRef(null);

<DiceGroup ref={diceGroupRef} diceCount={3}/>
<button onClick={() => diceGroupRef.current.roll()}>Ref Roll</button>

Advanced Usage

If you want more granular control over the dice in a group you can use DiceGroup as a wrapper and define Die components inside:

const thirdDie = useDie("third-die");

<DiceGroup onRollGroup={(result) => {
    console.log(result.values, result.sum, result.groupings)
}} diceSize={150}>
  <Die size={50} initialValue={6} keyboardListeners={['a']} useNumerals />
  <Die theme={`dark`} onClick={(roll) => {
      console.log(`rolling second die`);
      roll();
  }} />
  <Die id={`third-die`} onRoll={(value) => {
      console.log(value);
      doSomething(value);
  }} theme={`metallic`} />
</DiceGroup>

<button onClick={() => thirdDie.toggleFreeze()}>

You can use props to apply to all dice in a group and control/style individual die this way while still maintaining the group rolling/result logic.

Notes about GroupDice:

• The default behavior of clicking a group die is to freeze it. You can freeze programmatically as shown above as well.
• You can use a combination of the wrapper and Die components and diceCount prop. diceCount should be the total number of dice you want. If you do not have enough Die children, it will fill in with default Die components respecting the props of DiceGroup