Skip to content
RANDSUM — TypeScript Dice Rolling Library for Tabletop RPGs

Component Library

@randsum/component-library ships React components for embedding interactive dice rolling UIs into any web application. Self-contained with bundled styles.

Install

Section titled “Install”
Terminal window
bun add @randsum/component-library

Requires react, react-dom, @randsum/roller, and @randsum/notation as peer dependencies.

RollerPlayground

Section titled “RollerPlayground”

An interactive dice notation editor. Type a notation string, press roll, and see the total with a step-by-step breakdown panel.

import { RollerPlayground } from '@randsum/component-library'


export default function App() {
return <RollerPlayground defaultNotation="4d6L" />
}

Props

Section titled “Props”
PropTypeDefaultDescription
defaultNotationstring'4d6L'Initial dice notation shown in the input
size's' | 'm' | 'l''l'Overall size — scales font, padding, and chip
stackblitzbooleantrueShow the Code button to open notation in StackBlitz
classNamestring—Additional class name appended to the root element

Size variants

Section titled “Size variants”

size=“s”

size=“m”

size=“l” (default)

Theming

Section titled “Theming”

The component respects prefers-color-scheme automatically. Force a specific theme by setting data-theme on any ancestor:

<div data-theme="light">
<RollerPlayground />
</div>


<div data-theme="dark">
<RollerPlayground />
</div>

Astro usage

Section titled “Astro usage”

In an Astro project, use the client:only="react" directive:

<RollerPlayground client:only="react" defaultNotation="2d6+3" />

ModifierReference

Section titled “ModifierReference”

A compact reference grid of all supported dice notation modifiers. Useful as a help panel or notation guide.

import { ModifierReference } from '@randsum/component-library'


export default function HelpPanel() {
return <ModifierReference />
}

Props

Section titled “Props”
PropTypeDefaultDescription
coreDisabledbooleanfalseHide (grey out) the core xdY row
modifiersDisabledbooleanfalseHide (grey out) all modifier rows
onCellClick(cell: ModifierReferenceCell) => void—Called when a cell is clicked

Interactive usage

Section titled “Interactive usage”

Use onCellClick to build a notation-builder — clicking a modifier appends its notation to the input:

import { useState } from 'react'
import { ModifierReference } from '@randsum/component-library'
import type { ModifierReferenceCell } from '@randsum/component-library'


export default function NotationBuilder() {
const [notation, setNotation] = useState('4d6')


function handleCellClick(cell: ModifierReferenceCell) {
  if (cell.isCore) {
    setNotation('NdS')
  } else {
    setNotation(prev => prev + cell.notation)
  }
}


return (
  <>
    <input value={notation} onChange={e => setNotation(e.target.value)} />
    <ModifierReference onCellClick={handleCellClick} />
  </>
)
}

Overlay

Section titled “Overlay”

A portal-based overlay component used internally by the playground for tooltips and popovers.

import { Overlay } from '@randsum/component-library'


<Overlay visible={isOpen} onClose={() => setOpen(false)}>
<div>Overlay content</div>
</Overlay>

ErrorBoundary

Section titled “ErrorBoundary”

A React error boundary that catches rendering errors in child components and displays a fallback.

import { ErrorBoundary } from '@randsum/component-library'


<ErrorBoundary>
<RollerPlayground />
</ErrorBoundary>
Section titled “Links”