The BentoBox2 Developer Hub

Welcome to the BentoBox2 developer hub. You'll find comprehensive guides and documentation to help you start working with BentoBox2 as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Developer Documentation

Custom Fields

located in /config/ and /config.json

Custom fields may be defined on page templates, boxes, and theme (accessible via Theme Options). The key of each field is used to reference the value in the your template (e.g. if included in a config.json, the value of the field below would be accessible at theme.options.background_color), and the value contains various settings for this particular field.

The following is the definition of a custom field which uses all available settings. All of these settings are optional.

fields: {
  background_color: {
    title: "Background Color",
    /* This is the text displayed in the field's label in the
       administrator's panel. If this value isn't specified,
       BentoBox will infer a name by replacing the field's slug
       underscores with spaces and capitalizing each word. */ 
    type: "color",
    /* This controls the type of user interface component rendered
       when displaying this field. All possible values are listed in
       the "Types" section of the documentation. */
    helper: "Choose a light color for best results.",
    /* This shows a small line of text below your field intended to
       offer additional information to the end-user. */
    default: "#FFFFFF",
    /* This is the value initially used by the field when the theme
       is chosen. */
    display_logic: {"background_image":false}
    /* This controls whether or not this field is visible in the
       administrator's panel based on the value chosen for other
       fields. More information is available in the "Display Logic"
       section of the documentation. */

Avoid using dashes in field slugs.

Jinja2 will interpret dashes as subtraction, so use brackets to refer to these with square brackets (e.g. current.fields[my-custom-field]) or avoid the issue altogether by using underscores in variable names. BentoBox will also replace underscores, so you can typically avoid needing to explicitly define your fields' titles.


You may set the type in a field definition to any of the following values:

  • text - Displays a text input. Returns a string.
  • color - Displays a color picker. Returns a string the format of a rgba() value if the alpha value is less than one, otherwise a hex value.
  • number - Displays a number input. Returns a number.
  • wysiwyg - Display a wysiwyg. Returns a string. Plain text will be wrapped in a <p> tag by default.
  • image - Display an image uploader. Return the URL of the image. To ensure certain dimensions of the uploaded image, refer to the Resize Filter documentation.
  • file - Displays a file upload control. Returns a file url.
  • boolean - Display a checkbox. Returns a boolean.
  • code - Displays a code editor. Returns a string.
  • dropdown - Displays a dropdown. Expects a key options in this field definition to contain the choices to include in the dropdown. Options may be specified either as json, with the key as the value to be saved and the value as the text displayed for the option, or an array of strings, with the strings representing the value to be saved and the title will be inferred by replacing the string's underscores with spaces and capitalizing each letter. Leave a blank option if you wouldn't like to make this required.
  • relationship - Displays a dropdown from which the user may select a a box. You must specify the type of box you'd like the dropdown to populate with key box in the field's definition. Returns json of the box's data.
  • section - Displays a heading and fields defined under an items key below it. Sections are useful for targeting groups of fields for a section of a wireframe and for namespacing variables in your templates. (e.g. You would access the value of a field background_color in a section 'style' of your theme options by using {{ }}).
  • repeater - Displays an interface by which users can add, remove and re-order sets of fields specified under the key items. Returns an array of json, each representing a group of values entered by the user.

Concise Field Definitions

Developers have the options to write field definitions with varying degrees of specificity.

Fields may be concisely defined in json where the key is the name by which the value may be accessed in a template and the value is the field's type. BentoBox will infer a name by replacing the field's slug underscores with spaces and capitalizing each word.

Each of the following are valid and equivalent:

fields: {"first_name": "text", "last_name": "text"}

fields: {
  "first_name": {"title":"First Name", type:"text"},
  "last_name": {"title":"Last Name", type:"text"}

Display Logic

The display_logic setting allows fields to be shown and hidden based on the value of other user selected fields. These are typically used to hide fields which become irrelevant based on the settings of others, as to de-clutter the administrator's panel. For example, if you have a boolean field which controls whether or not a header is displayed, you may want to hide the field which control's this header's background color when the header display control is unchecked.

The display_logic setting expects an array of rule groups. If any of the rule groups are satisfied, the field displays. A rule group is represented by a dictionary, which consists of key/val pairs representing rules. The rule group is satisfied if every rule (represented by a key/value pair) is true.

Each rule's key described the path to the value you'd like to compare.(This is the same as what you would use in a template to reference this value after calling .fields. (or theme.options. in the case of Theme Options.) Accordingly, if you are referencing a field within a section, it must be referenced from the base of the field's structure, not the base of the section.

If you are using display logic on subfields of a repeater, the path to which the operator and value are being evaluated against is relevant to the root of the repeater field.

Each rule's value is json with two keys:

  • operator - This is the logical operator you'd like to use to compare the referenced field's value with the value specified below. Possible values are: ==, !=, <, >, <=, and >=.
  • value - This is the value you'd like to compare to the referenced field's value, using the operator specified above.


// Sample Theme Configuration file using 

  theme: {
	  options: {
      display_header: "boolean",
      header_color: {
        type: "color",
        display_logic: {
          display_header: {
            operator: "==",
            value: true

As with the custom fields, you may define your display logic using a more concise syntax. If only a string is specified, it is assumed to be the only rule group containing a rule that expects the string to be the path to the field we'd like to compare to, the operator is assumed to be ==, and the value is assumed to be true.


  	"options": {
     "header": {
        "items": {
          "background_color": {

Each of the following are valid and equivalent display_logic values:

"display_logic": "header.display",
"display_logic": ["header.display"],
"display_logic": [{"header.display": true}],
"display_logic": [{"header.display": {"operator": "==", "value": true} }]

Custom Fields

located in /config/ and /config.json