Option Types

Option types are the building blocks of Unyson+ settings, meta boxes, and shortcode options. The framework ships with many — text, textarea, select, switch, color, typography, image/upload, gallery, spacing, gradient, box-shadow, and more.

Every option has type as a required parameter. Its value should be an existing registered option type.

Defining options

Options are declared as a PHP array:

<?php
$options = array(
    'heading' => array(
        'type' => 'text',
        'label' => __( 'Heading', 'fw' ),
        'value' => 'Hello world',
    ),
    'accent' => array(
        'type' => 'color-picker',
        'label' => __( 'Accent color', 'fw' ),
        'value' => '#ffcc00',
    ),
);

Reading saved values

<?php
// Theme settings
$accent = fw_get_db_settings_option( 'accent' );

// Post meta (e.g. from a Custom Fields group or a meta box)
$heading = fw_get_field( 'heading' );

Adding a new option type

New option types live in framework/includes/option-types/. Each registers a class extending FW_Option_Type. For a complete worked example (the PHP class, the prefixed CSS, and the fw:options:init JS), see Create an option type. The conventions below are the rules that example follows.

HTML

All option types must have a .fw-option-type-{type} class on the main/wrapper html element.

CSS

If the option type has css, all rules must be prefixed with the .fw-option-type-{type} class:

/* correct */
.fw-option-type-demo .some-class {
    color: blue;
}

/* wrong */
.some-class {
    color: blue;
}

tip

This is done to prevent css conflicts.

JavaScript

All javascript must stick to the .fw-option-type-{type} class and work only within the main/wrapper element (no events attached to the body). If the option type has custom javascript events, those events must be triggered on the main element.

$someInnerElement.closest('.fw-option-type-demo')
    .trigger('fw:option-type:demo:custom-event', {some: 'data'});

If it's specified in the documentation that an option type has custom events, it means that you can attach event listeners on the elements with the .fw-option-type-{type} class (not on body or fwEvents). Some events send data that can be accessed this way:

jQuery('.fw-option-type-demo#fw-option-demo')
    .on('fw:option-type:demo:custom-event', function(event, data){
        console.log(data);
    });

danger

Do not confuse .fw-option-type-{type} with the .fw-backend-option-type-{type} class which is used internally by the framework and should not be used in option type scripts.

Built-in option types

All 54 built-in types, grouped by what they're for. Click any type for its reference and a copy-pasteable example.

Text & rich input

Type	For
text	A single-line text input
short-text	A narrow text input
medium-text	A mid-width text input
textarea	Multi-line plain text
password	A masked text input
number	A numeric input with min / max / step
unit-input	A number paired with a unit selector (px / rem / em / %)
code-editor	A syntax-highlighted code editor
wp-editor	The WordPress rich-text (TinyMCE) editor
html	Render arbitrary HTML in the form (no stored value)
hidden	A stored value with no visible control

Choice

Type	For
select	A single-choice dropdown
short-select	A narrow dropdown
select-multiple	A multi-choice dropdown
multi-select	A tag-style multi-select (posts, terms, users, …)
radio	A single choice as radio buttons
radio-text	Radio buttons rendered as a segmented control
checkbox	A single on/off checkbox
checkboxes	Multiple checkboxes
switch	An on/off toggle
image-picker	Choose one option by clicking an image swatch

Color

Type	For
color-picker	A single solid color
rgba-color-picker	A color with alpha / opacity
predefined-colors	Pick from a fixed palette
predefined-colors-color-picker	A palette preset or a custom color
predefined-colors-color-picker-compact	The compact preset-or-custom picker
gradient	A two-stop gradient
gradient-v2	A multi-stop gradient with angle and type

Media & icons

Type	For
upload	Upload or select one file from the Media Library
multi-upload	Select multiple files / a gallery
background-image	An image with position / repeat / size
background-pro	Full background: color + gradient + image + video layers
oembed	Embed by URL (YouTube, Vimeo, …)
icon	Pick an icon (Font Awesome)
icon-v2	Pick an icon from multiple packs, or upload a custom SVG
map	A location picker returning coordinates + address

Typography, spacing & effects

Type	For
typography	Font family / size / weight / style / line-height / color
typography-v2	The modern typography control (+ Google Fonts)
spacing	Margin / padding per side, with per-device overrides
box-shadow	A box-shadow builder

Sliders & ranges

Type	For
slider	A single-value slider
range-slider	A min / max range slider

Date & time

Type	For
date-picker	Pick a date
datetime-picker	Pick a date and time
datetime-range	Pick a start / end date-time range

Presets & pickers

Type	For
button-presets	Manage reusable button-style presets
button-style-picker	Pick a button preset with a live preview
image-style-picker	Pick an Image Style preset with a live swatch preview

Composite & repeatable

Type	For
multi	Group several options into one stored value
multi-picker	Reveal different sub-options based on a picker choice
responsive	Wrap any control to make it per-device (Phone / Tablet / Desktop)
popup	Edit a set of options inside a modal
popover	Edit options inside an inline popover panel
addable-option	A repeatable single option (add / remove rows)
addable-box	A repeatable group of options (add / remove boxes)
addable-popup	Repeatable items, each edited in a popup