# react-dice

> A drop-in react component for creating dice, with a robust information set to allow easy use.

Latest version **1.0.1** (published 2016-07-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-dice
pnpm add react-dice
yarn add react-dice
bun add react-dice
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2016-07-03 |
| First published | 2016-06-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Ben Conolly |
| Maintainers | noviny |
| Keywords | dice, dungeons and dragons, react |

## Links

- npm: https://www.npmjs.com/package/react-dice
- Repository: https://github.com/noviny/react-dice
- Homepage: https://github.com/noviny/react-dice#readme
- Issues: https://github.com/noviny/react-dice/issues
- npm.io page: https://npm.io/package/react-dice

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.0.1 (latest) — 2016-07-03
- 1.0.0 — 2016-07-02
- 0.1.0 — 2016-06-17
- 0.0.3 — 2016-06-17
- 0.0.2 — 2016-06-12
- 0.0.1 — 2016-06-12

## README

# React-Dice
A drop-in react component for creating dice, with a robust information set to allow easy use.

The main part of this package is the `<Dice>` component.

The package also contains a number of functions to roll dice, or create dice objects with their own `get()` functions to roll the dice that the object represents.

## The General Use-Case
```
import { Dice, rolls } from 'react-dice';

<Dice
	rolls={[roll(3, 6), roll(1, 8), roll(1, 10)]}
	showResults
	bonus={6}
/>
```

With just this, you can drop a dice roller onto your screen.

Once you have your dice roller on the screen, push the shiny roll button (actual shininess will come with a future patch), to see both a total, as well as your array of rolls. Maximum rolls will be green, while minimum rolls will be red.

If you realise that the dice you have are no longer what you want, you can click on any dice to make it editable, changing the quantity of dice to use, or the type of dice.

```
// TODO: allow you to add another dieType to your set, or delete one, instead of just setting the number to zero
```

## How does it work (and how can I make it work for me)
The `rolls` prop is where most of the heavy lifting is going on. It accepts an array of objects that conform to the following shape:

```
{
	dieCount: 1,
	dieType: 6,
	bonus: 3
}
```

If you want, you can generate these objects in any way you want, and pass them into the rolls array. The rolls array will assign default values to any object in the array missing one or more of the above properties, defaulting `dieCount` to 1, `dieType` to 6, and `bonus` to 0.

Finally, all the bonuses from your dice are bundled together as a single bonus applied to the entire set of dice.

If you pass in `showResults`, you will see a list of what each individual dice rolled is, otherwise you will just have what you are rolling and the total displayed, for when the totals of individual dice is not relevant.

`bonus` is an optional prop to help ease of composure, in case you have bonuses to the total that are not associated with any individual set of dice within the roll.

## `roll` and other logic functions


You may note that we are calling `roll(3, 6)` instead of passing in an object. `roll()` is one of three logic functions that allow you to work more easily. Like an individual dice object, `roll` takes in three variables, which are, in order, the dieCount, the dieType, and the bonus. Like the `<Dice>` component itself, `roll` has fallbacks, however it falls back to 1 die with twenty sides and no bonus.

The object generated by roll also has a `get` method on it, if you have a need for dice logic without a component anywhere, you can do so like this:

```
import { roll } from ‘react-dice’;

var myRoll = roll(3, 6, 5)
total = myRoll.get()

```

Note that `roll()` returns us an object, which has internals that look like this:

```
rollObj = {
	dieCount: 3,
	dieType: 6,
	bonus: 5,
	lastRoll: 0,
	results: [
		{ type: 6, value, 0 },
		{ type: 6, value, 0 },
		{ type: 6, value, 0 }
	]
	get: function()
}
```

If you have a roll object, you are able to go in and manually edit the count, type or bonus, and new calls to `rollObj.get()` will respect the new values. The results will also be regenerated, and the total of our lastRoll is saved.

This leads very neatly into our next logic function, `newRoll()`

`newRoll()` also accepts the same kinds of arguments, and has the same defaults, but instead of returning an object for future use, is responsible for returning immediate results, and will not need that kind of roll again. The standard use-case is as follows:

```
import { newRoll } from 'react-dice';

var total = newRoll(3, 6, 5).total

```

You may note that we are asking here for the total. newRoll returns both the total and the array of results, and so will generally return an object. Here we only want the total, however we could instead run:

```
var ourResults = newRoll(3, 6, 5)
```

Which will store for us both a total and an array of the individual dice values in the same format as the results in our `roll` object.

Our final logic function is `rolls()`, which serves the same purpose as `roll()` but for sets of multiple dice types. Unlike `roll()` or `newRoll()`, `rolls` does not take in dieCount or dieType as arguments, but instead takes in an array of roll objects as its first argument, and a bonus as an optional second argument. As such `rolls()` could be called like so:

```
var complexRoll = rolls({
	{ dieCount: 3, dieType: 6, bonus: 5 },
	{ dieCount: 1, dieType: 8 },
	{ dieCount: 2, dieType: 10 },
}, 5)

```

This mirrors how the `<Dice>` component works, and is what that component is actually using.

The internals of our new complexRoll object will look like this:

```
{
	rolls: [{
		{ dieCount: 3, dieType: 6 },
		{ dieCount: 1, dieType: 8 },
		{ dieCount: 2, dieType: 10 },
	}],
	lastRoll: 0,
	results: [],
	bonus: 10,
	get: function()
}
```

Wherever possible, this mirrors the internals of our singular roll object, however it has an array of rolls that holds an array  of dieCount, dieType pairs. Most importantly it has a `get()` function that will return the total for you, as well as access to your lastRoll total, and the results array.

## Saving Dice objects

As they are javascript objects, it is relatively easy to save a dice object to a mongo database. A word of caution that doing so will strip the get function, so while it is useful to save dice to pass back to the `<Dice>` component, they will no longer be dynamic.

```
// TODO: Add rehydration methods for dice saved in a database.
```

---
_Source: https://npm.io/package/react-dice · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._