VDiceRoller Component

Interactive playground - adjust the controls to see live updates

<v-dice-roller
notation="{{ config.notation }}"
variant="{{ config.variant }}"
input-type="{{ config.inputType }}"
result-size="{{ config.resultSize }}"
:show-history="true"
:show-details="true"
:show-presets="true"
:minimal="true"
/>

# Usage

Basic examples showing common configurations of the dice roller component.

✨ Two-Way Binding with v-model
Use v-model:notation to sync the notation with parent component state. Changes in the component automatically update the bound variable, and vice versa.
<script setup> import { ref } from 'vue'; const diceNotation = ref('2d6+3'); </script> <template> <VDiceRoller v-model:notation="diceNotation" /> <!-- External input synced to same data --> <input v-model="diceNotation" /> </template>
🛡️ Validation Rules
Add Vuetify-style validation rules to enforce game-specific constraints. Rules run before each roll.
<script setup> const rules = [ v => !!v || 'Notation required', v => { const match = v.match(/(\d+)d/); return !match || parseInt(match[1]) <= 10 || 'Max 10 dice'; } ]; </script> <template> <VDiceRoller notation="2d6" :rules="rules" @validation-error="onError" /> </template>
Default
Standard configuration with text input and roll button.
With History
Track previous rolls with the history feature.
With Presets
Quick roll buttons for common dice combinations.

# Input Types

Choose between text input, dropdown select, or a combination of both.

Text Input
Free-form text input for custom notation.
Select Dropdown
Choose from preset dice combinations.
Combo (Text + Select)
Text input with dropdown for quick access.

# Visual Styling

Adjust the size and layout to fit your design needs.

Small Result
Compact result display for tight spaces.
Large Result
Prominent result display for emphasis.
Compact Variant
Reduced spacing throughout component.
Inline Variant
Horizontal layout for inline use.
Minimal Mode
Just the result, no notation label.

# Theming

Customize colors with CSS variables - no component changes needed.

Default Theme
Out-of-the-box purple gradient.
Orange & Black
Bold color scheme.
.theme-orange-black { --dice-primary-color: #ff6b35; --dice-secondary-color: #1a1a1a; }
Green & Teal
Fresh, natural colors.
.theme-green-teal { --dice-primary-color: #10b981; --dice-secondary-color: #14b8a6; }

# API Reference

Props

Name Type Default Description
notation String '2d6' Initial dice notation (e.g., "2d6+3"). Supports v-model: v-model:notation
variant String 'default' Display variant: 'default', 'compact', or 'inline'
input-type String 'text' Input type: 'text', 'select', or 'combo'
result-size String 'medium' Result display size: 'small', 'medium', or 'large'
show-history Boolean false Display roll history
show-details Boolean true Show individual roll breakdown
show-presets Boolean false Show quick roll preset buttons
minimal Boolean false Hide notation label, show only result
auto-roll Boolean false Automatically roll on mount or notation change
rules Array [] Validation rules. Each rule: (notation) => true | false | string
disabled Boolean false Disable rolling (button becomes unclickable)
loading Boolean false Show loading state (⏳ in button, prevents rolling)
animation-plugin Object null Animation plugin with async roll(notation, options) method. Result displays after animation completes.

Slots

Name Props Description
prepend { notation, roll } Content before the component
button { roll } Custom roll button content
result { result, notation, total, rolls, modifier } Complete custom result display
result-total { total } Custom total display
actions { result, history, roll, clear } Action buttons area
history-item { item, index } Custom history item rendering
append { result, history, roll } Content after the component

Events

Name Payload Description
@before-roll { notation: string } Emitted before the roll is executed
@after-roll { notation, total, rolls, modifier } Emitted after the roll completes successfully
@roll { notation, total, rolls, modifier } Emitted after roll (backwards compatibility)
@error Error Emitted when roll fails (invalid notation)
@validation-error string Emitted when validation rules fail
@update:notation string Emitted when notation changes (for v-model)

Exposed Methods & State

Access via template refs for programmatic control:

Name Type Description
roll() Method Trigger a roll programmatically
clearHistory() Method Clear the roll history
result Ref Current roll result (reactive)
history Ref Roll history array (reactive)
error Ref Error message if any (reactive)
notation Ref Current notation (reactive)

CSS Variables

Variable Default Description
--dice-primary-color #667eea Primary button and accent color
--dice-secondary-color #764ba2 Secondary gradient color
--dice-border-radius 4px Border radius for inputs and buttons
--dice-text-color #333 Primary text color
--dice-bg-color white Background color for inputs
--dice-result-text white Text color in result display