Character Vault
Any Concept / Any System
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Button"

From Roll20 Wiki

Jump to: navigation, search
m (add action button naming issue)
m (Action Button)
Line 199: Line 199:
===Reset Stats===
== Compendium Button ==
== Compendium Button ==

Revision as of 10:28, 12 September 2020

Examples of default Roll Button, Action Button, and Compendium Button

Main Article: Building Character Sheets

This page is about creating/editing Custom Character Sheets(Pro feature), and how to use <button> HTML element.

The <button> have three roll20-specific types that can be used in character sheets; type="roll", type="action", type="compendium".

This guide gives a rundown of how each type is used, together with some examples on how to implement common things. More examples could be added under the appropriate section.



The code for the Example Buttons displayed at the top of this page:

<button type="roll" name="roll_exampleroll1" value="/roll d20 + 4" ></button>
<button type="roll" name="roll_exampleroll2" value="/roll d20 + 4">Roll Button</button>
<button type="action" name="act_exampleaction" >Action Button</button>
<button type="compendium" name="act_actionexample" >Compendium Button</button>

Roll Button

The common use for buttons in Roll20 is for making a roll button. By default, roll buttons show a d20 icon, and if any text is added to be displayed on the button, it is shown after the d20 icon.


<button type="roll" value="/roll 1d20 + @{Bluff}" name="roll_BluffCheck"></button>

  • the type-attribute must be set to roll
  • the roll macro is defined in the value-attribute.
  • the optional name-attribute allows the roll to be referenced in external Macros and Abilities. The name must be prefixed with roll_ for this to work, and each roll button should have a unique name. Buttons in repeating sections automatically gain a unique prefix/suffix in their name.

To call a named roll button in the chat, it works similarly like calling a defined Ability macro from the A & A tab, e.g. %{Bob|BluffCheck}. This will call the "BluffCheck" button of the character named "Bob".

Roll Macro

To construct more advanced rolls, you should check the Macros and the Dice Reference pages.

The roll macro is placed in the value field.

<button type="roll" value="/roll 1d20 + @{Bluff}" name="roll_BluffCheck"></button>

For creating more advanced rolls, you can choose to have parts of the macro defined in an attribute(and more easily edited by the player or sheetworkers, such as:

<button type="roll" value="&{template:default} {{name=Magic attack (@{character_name}) }} {{Roll=[[@{intelligence}d6 + @{mana}d6 ]]}}" name="roll_Magic1"></button>

See also:

Roll Query, with Toggle

In your roll macro you can include an option roll query, that gives a popup asking if you want to add some modifier, either through a simple text field, or a dropdown. However, some users of the sheet might not always use it, so an option to turn on/off this popup is a good idea.

Here is a simple way you can have an optional element in your rolls that can be toggled with a simple checkbox.

<span>Modifier popup for rolls?<input type="checkbox" name="attr_rollmod" value="?{Modifiers?|0}"></span>
<input type="number" name="attr_composure" value="1" >
<button type='roll' name='roll_composure' value='&{template:default} {{name=Composure check}} {{result=[[(@{composure} + @{rollmod})d6]]}}'></button>
<input type="number" name="attr_reaction" value="1" >
<button type='roll' name='roll_reaction' value='&{template:default} {{name=Reaction check}} {{result=[[(@{reaction} + @{rollmod})d6]]}}'></button>

You can then use the checkbox's rollmod-attribute in multiple buttons at the same time, which means you can toggle the roll query on the whole sheet at the same time.

If you want to have more options, you can replace the checkbox with an <select> like this:

<select name="attr_rollmod">
   <option value="0" checked>Nothing</option>
   <option value="?{Modifier?|0}">Ask for Roll Modifier</option>
   <option value="@{level}">Add level to roll</option>


More info: Macros#Rolling_For_Initiative

To send a roll result directly to the Turn Tracker, first, select the Token you wish to roll for initiative, use make a roll that has the &{tracker} in it.


/roll 1d20 + 5 &{tracker}

&{template:default} {{name=Initiative}} {{Roll=[[d10+@{wis_mod}]]}} &{tracker}

Roll Template

Main Article: 'Roll Templates

With your roll buttons, you can make simple rolls like /roll d20 + @{bluff}}, but in many cases you might want to make use of Roll Templates to create better output of your rolls. Roll Templates can also be used to create pseudo-conditional behavior, such as showing a roll section only if you roll a critical success on a previous section.

There exist a Default roll template that can be accessed in any sheet, but it's a much better idea to at least use Jakob's Better Default Rolltemplate which is just a cleaner version of the default template, and is at least a start for creating your own.

To include Jacob's roll template to your sheet, simply copy the HTML code and save it at the end of your sheet's HTML-file, and do the same for the CSS code. You similarly copy other sheet's roll template to your sheet to enable their use.


Instead of using just normal macros in your rolls, you can choose to include API commands(require for that API to be installed in a game to work.

Depending on how the API you want to incorporate works, you might be able to mix normal macros and API commands in the same button, like using the stat-editing API to automatically remove an arrow when you roll an corresponding attack.

If you use these in sheet that will be published on Roll20 GitHub, you need to make API-based rolls optional.

Star Wars FFG and the Genesys sheet are two examples of sheet that uses custom API for rolling their dice, as the default Roll20 macros can't handle the custom things required.

Wild Die Example

Script:Wild Dice is another API example that could be used in roll buttons.

Button to roll 5d6+2 according with the Wild Die method(and have the highest rolled normal dice be removed from the result if you roll a fumble on your wild die):

<button type="roll" value="!wd [[5d6+2]]" name="roll_wilddieexample" ></button>

Action Button

Action buttons can be used as events to trigger Sheetworkers.


<button type="action" name="act_reduce">Reduce</button>

  • the type-attribute must be set to action
  • the name-attribute must be defined, and have a act_ prefix to function
  • Do not use action button names that include underscores, otherwise they will fail to trigger as a detectable event for sheetworkers.

It a good idea to display text inside

Two common uses:

  • Swap between sheet tabs/visible areas (CSS Wizardry Example)
  • Increment stats, such as ammo usage

Adjust Stats Examples

Made by GiGs and expanded here. Each step is expanded and commented for clarity.

Add one to the level stat , when a button is clicked.

Create an action button on the sheet:

<button type="action" name="act_add">Add level</button>

Then add this code the the sheetworker section of the sheet:

on('clicked:add', function() {
    getAttrs(['level'], function(values) {
        // get the level stat, and coerce into a numerical value.
        const level = +values.level || 0; 
        // increase by 1
        const newlevel = level +1;
        // save the updated attribute to the sheet
           level: newlevel 

Reducing several stats with one button press.

Create an action button on the sheet:

<button type="action" name="act_reduce">

Then add this code the the sheetworker section of the sheet:

on('clicked:reduce', function() {
    // make an array of the attributes you plan to adjust, for ease of use later
    const attributes = ['list of attributes to adjust'];
    getAttrs(attributes, function(values) {
        const settings = {}; // make a variable to hold the changed attributes
        // loop through the attributes, get the value, then subtract 1
        attributes.forEach(att => {  // in each go through the loop, "att" becomes the next attribute
            let tempattribute = +values.att || 0;
            tempattribute -= 1;
            // store the changed attribute in the settings variable:
            settings[att] = tempattribute;
        // save the updated attributes to the sheet

Reset Stats

Compendium Button

Main Article: Compendium Button

The compendium button can be used to open a compendium entry directly from a character sheet, in the same way as if you clicked on an entry in the in-app compendium. This can be used as a more convenient way to access rules and descriptions, for example, for a spell, the compendium button can be used to easily view the full description for that spell.

The syntax is <button type="compendium" value="<entryname>">.


<button type="compendium" value="Bard">Bard</button>

Styling Roll Buttons

Styling Roll Buttons shows a few examples on how to style your button to look differently.

Examples include; removing the default d20 icon, replacing the default with a d6, using an image in a button, and making a button blend in. The Action and Compendium buttons looks slightly different by default(see picture at top of article).

See Also