@scriptless/react-dice

A React dice component with inky rolling animations.

I designed this component to work a little bit like an input. When it's enabled, a click from a user is a request for a new dice roll. The component can handle coming up with a value - or in cases where cheating is a concern, it can make a call to your server to get a new value using getNextValue.

When a roll is done, the component will deliver its value to its onChange. If you want the dice to show a particular value before its first roll, pass that down with the initialValue prop.

Installation

npm install @scriptless/react-dice --save

Basic Usage

import { Dice } from '@scriptless/react-dice';
import '@scriptless/react-dice/styles.css';

function App() {
  return <Dice onChange={(value) => console.log('New value:', value)} />;
}

Group Usage

import { DiceGroup, Dice } from '@scriptless/react-dice';
import '@scriptless/react-dice/styles.css';

function App() {
  const diceValueFromServer = useFetchValue();

  const [
    diceValue, // use me for other UI elements, no need to pass me to the dice component
    setDiceValue,
  ] = useState(undefined);

  return (
    <DiceGroup
      onChange={setDiceValue} // this will get called with an array of three values
    >
      <Dice />
      {/* dice will work with any arbitrary dom structure */}
      <div style={{ border: '1px solid black', padding: 40 }}>
        <Dice />
        <div style={{ position: 'absolute', top: 0 }}>
          <Dice />
        </div>
      </div>
    </DiceGroup>
  );
}

API Reference

Dice Component Props

| Prop | Type | Default | Description | | -------------------- | --------------------------------- | --------- | ------------------------------------- | | initialValue | number | 1 | Initial value of the die (1-6) | | onChange | (value?: number) => void | - | Callback fired when die value changes | | getNextValue | () => number \| Promise<number> | random | Function to generate next die value | | disabled | boolean | false | Disables die rolling | | size | number | 66 | Size of the die in pixels | | pipSize | number | 12 | Size of the pips in pixels | | borderColor * | string | 'black' | Color of die border | | borderRadius | number | 8 | Border radius in pixels | | borderWidth | number | 3 | Border width in pixels | | backgroundColor * | string | 'white' | Die background color | | pipColor * | string | 'black' | Color of the pips |

* be careful with these props, because this component works by blurring and contrasting for the inky effect, colors of similar luminosity may cause a strange strobe effect during roll

DiceGroup Component Props

| Prop | Type | Default | Description | | ----------- | ---------------------------- | ---------------------------------- | ----------------------------------------- | | onChange | (values: number[]) => void | - | Callback fired when any die value changes | | disabled | boolean | false | Disables rolling for all dice | | className | string | - | Additional CSS class | | style | CSSProperties | { display: 'flex', gap: '10px' } | Inline styles |

Advanced Usage

Get your dice values from a server

const CustomDice = () => {
  const diceValueFromServer = useFetchFromServer();

  const [
    diceValue, // use me for other UI elements, no need to pass me to the dice component
    setDiceValue,
  ] = useState(undefined);

  const getNextValue = async () => {
    const response = await fetch('https://api.random.org/v1/dice');
    const data = await response.json();
    return data.value;
  };

  return (
    <Dice
      initialValue={diceValueFromServer}
      onChange={setDiceValue}
      getNextValue={getNextValue}
    />
  );
};

Styled Dice

const StyledDice = () => (
  <Dice borderWidth={2} borderRadius={20} size={80} pipSize={14} />
);

License

MIT © Gus Nordhielm

To do, contributions welcome

• [x] Better same-to-same number animations, e.g. two dots should switch sides, one dot should pulse
• [ ] Use rolling as a loader, when I'm waiting for an async getNextValue, I should see feedback immediately
• [ ] When I rapid click a dice item, they weirdly alternate rolls
• [ ] Custom colors are causing weird behaviors - e.g. dark bg with dark pips make them bleed a lot, perhaps there's a way of using b/w pips and then masking them over the background. Also the background is flashing with the contrast setting.
• [ ] On initial click, there's like a little bounce - but this happens inconsistently and sometimes twice, worth making that consistent