PHPackages                             simplicateca/metasettings - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. simplicateca/metasettings

ActiveCraft-plugin

simplicateca/metasettings
=========================

Meta Settings is a custom field plugin for Craft CMS 5+

5.3(4mo ago)61151MITJavaScript

Since Nov 4Pushed 2w ago1 watchersCompare

[ Source](https://github.com/simplicateca/craft-meta-settings-field)[ Packagist](https://packagist.org/packages/simplicateca/metasettings)[ RSS](/packages/simplicateca-metasettings/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (22)Used By (1)

MetaSettings - Craft CMS Custom Field
=====================================

[](#metasettings---craft-cms-custom-field)

MetaSettings is a JSON configured, custom field type plugin for Craft CMS 5+. It field presents like a standard Craft CMS [Dropdown Field](https://craftcms.com/docs/5.x/reference/field-types/dropdown.html) which itself makes use of the [Selectize JS library](https://selectize.dev/).

Hiding under the hood of MetaSettings are a bunch of features aimed at improving the overall content [Author Experience (AX)](https://www.amazon.com/Author-Experience-Bridging-technology-management/dp/1937434427) and developer templating experience in Twig.

[![](https://camo.githubusercontent.com/a8132c80f59a81c727935dbda51dbaeb81d7790d39365a8b404c456900f32a2d/68747470733a2f2f692e696d6775722e636f6d2f5955744d616e592e706e67)](https://camo.githubusercontent.com/a8132c80f59a81c727935dbda51dbaeb81d7790d39365a8b404c456900f32a2d/68747470733a2f2f692e696d6775722e636f6d2f5955744d616e592e706e67)

```
**This is a Beta Release!**

```

Overview
--------

[](#overview)

- Configurable **Inline Tooptips** and **Help/Documentation Modal** for improving author experience.
- Definable **Virtual Input Fields** that are only displayed via the `Settings` button next to the Dropdown field. Progressive disclosure FTW!
    - Supported field types include: Plain Text, Number, Radio Group, Lightswitch, Dropdown/Select, Money, Color, Icon, Date, Time
- Each field option can have separate or shared virtual input fields.
- Each option can also have shared or unique **Settings Tokens** that are made accessible in the Twig templates in addition to the selected field values.
- Configure fields via `.json` files stored in the Craft CMS `templates` folder.
- Since the config files are still technically parsed as Twig files, you can get silly creative with advanced configurations.

[![](https://camo.githubusercontent.com/7f0fd24426cd699e6ba3e7cdfb58d16efac417800800b367e7a2d0b7f2250c53/68747470733a2f2f692e696d6775722e636f6d2f476934303951652e706e67)](https://camo.githubusercontent.com/7f0fd24426cd699e6ba3e7cdfb58d16efac417800800b367e7a2d0b7f2250c53/68747470733a2f2f692e696d6775722e636f6d2f476934303951652e706e67)

[![](https://camo.githubusercontent.com/c7faa06d97b935f50c48d7562b508329485243c85756e114c3ba9f41bd5b6c50/68747470733a2f2f692e696d6775722e636f6d2f47746e624f50692e706e67)](https://camo.githubusercontent.com/c7faa06d97b935f50c48d7562b508329485243c85756e114c3ba9f41bd5b6c50/68747470733a2f2f692e696d6775722e636f6d2f47746e624f50692e706e67)

Installation
------------

[](#installation)

This early release version is not currently available on the Craft Plugin store, and can only be installed via Composer.

**Requires Craft CMS 5+**

Run `composer require "simplicateca/metasettings:^5.1" -w && php craft plugin/install metasettings` and then enable the plugin from "Settings &gt; Plugins"

composer require "vaersaagod/seomate:^3.1.1" -w &amp;&amp; php craft plugin/install seomate

Configuration
-------------

[](#configuration)

Options for each MetaSettings field are stored in a JSON file within the Craft CMS `templates` folder rather than requiring them to be input via the Craft CMS Control Panel.

That means, when you want to add, change, or remove options from a Dropdown, you can do so by editing a JSON file in your code editor, rather than having to go into the Control Panel and edit or re-save individual fields.

This is particularly useful for fields that are used across many Matrix Block types, reducing the need to update the same options in many places, and reducing the risk of human error.

### Sample `.json` Files

[](#sample-json-files)

Sample JSON config files can be found in the plugins ['src/templates/samples' folder](https://github.com/simplicateca/craft-meta-settings-field/tree/main/src/templates/samples/config).

Additionally, each file in that folder can be used in dev mode to demonstrate the fields capabilities and functionality:

- `_metasettings/config/simple.json`
- `_metasettings/config/all-inputs.json`
- `_metasettings/config/button-only.json`

Twig Templating
---------------

[](#twig-templating)

Each option in a MetaSettings field allows for additional data to be associated with it that you can use in place of creating logic in Twig to match the value of a dropdown field.

Within the JSON configuration for a field, you can have an attribute called `settings` that allows for any number of key-value pairs (strings, arrays, etc) to be passed along into Twig.

For example, if you had a MetaSettings field `fieldName` with this configuration:

```
{
    "label": "Option One",
    "value": "one",
    "settings": {
        "usefulText": "This is some useful text"
    }
}

```

You could then reference the **settings.usefulText** in your Twig templates like: `{{ entry.fieldName.usefulText }}`

This of course would only work if you "Option One" was selected in the `fieldName` field. If a different option were selected, the settings variables and their contents might be different (that's up to you!).

Why would this ever be useful? Plenty of reasons!

```
Explain With Examples...

```

### Instant Updates

[](#instant-updates)

Because changes to the JSON file are immediately reflected in all instances of the field, you can use this to easily tweak any number of settings across many templates or entires without having to go into the Control Panel and edit/resave individual records.

Inline Documentation
--------------------

[](#inline-documentation)

While Craft CMS allows for us to associate instructions with each field, these only apply to the field as a whole, and not to individual option selected within a Dropdown.

MetaSettings fields allow for the creation of inline documentation for each option, which can be accessed via tooltips, modals, or links to external resources.

Modal content is loaded from a Twig file of your choice, and the Twig template can make use of dynamic information about the field and selected option to decide what kind of documentation to display.

```
TODO: Outline Different documentation settings in the JSON config

```

Virtual Input Fields
--------------------

[](#virtual-input-fields)

Like a regular Dropdown field, the MetaSettings field stores the value of the `` selected by the user. However, it can also be used to store multiple additional inputs fields associated with each option.

This can be useful for situations where the selected option has fine-tuning "follow-up questions", especially if the extra inputs are presentational rather than content model in nature, and likely don't warrant their own [Custom Field](https://craftcms.com/docs/5.x/system/fields.html).

Nobody likes a cluttered content model, and this can help keep things tidy.

### Field Configuration

[](#field-configuration)

The configuration structure used for the virtual field config is identical to the one used by the Craft core `_includes/forms.twig` file. In fact, most of the fields are directly generated by that.

### Available Field Types

[](#available-field-types)

Available input fields include:

- Plain Text
- Number
- Radio Group
- Lightswitch
- Dropdown/Select
- Money
- Color
- Icon
- Date
- Time

See [all-inputs.json](https://github.com/simplicateca/craft-meta-settings-field/blob/main/src/templates/samples/config/all-inputs.json) for an example of how to configure each of these fields.

Dynamic Configuration
---------------------

[](#dynamic-configuration)

MetaSettings only suggests `.json` files when attempting to autocomplete the file path within the field configuration screen.

However, MetaSettings it is happy to accept any file type that can be parsed as a Twig template provided:

1. You enter the file path manually without the aid of autocomplete (the horror!)
2. The file outputs a valid JSON array of options

MetaSettings provides an `element` variable which can be accessed in any Twig tags or commands from within any MetaSettings config file (regardless of file extension).

This `element` variable contains information about the element that the field is attached to, as well as that elements' owner (if applicable as in cases of matrix fields).

These are the fields that are available on the `element` variable:

`element.section` - The handle for the [Section](https://craftcms.com/docs/5.x/reference/element-types/entries.html#sections) associated with the direct element that the field is attached to (if applicable).

`element.type` - The handle for the [Entry Type](https://craftcms.com/docs/5.x/reference/element-types/entries.html#entry-types) associated with the direct element that the field is attached to (if applicable).

Additionally, for cases where the MetaSettings field is attached to a Matrix block, the `element` variable will also contain an `owner` variable which contains the same fields as the `element` variable, but for the owner of the Matrix block.

This means that instead of configuring a MetaSettings field with a static `.json` file, you may consider some of the following techniques.

### Configuration with `.twig` instead of `.json`

[](#configuration-with-twig-instead-of-json)

**field-config.twig**

```
{% set fieldOptions = [
    {
        "label": "Option One",
        "value": "one",
        "settings": {
            "template" : "_layouts/basic.twig",
            "fizz": true
        }
    },{
        "label": "Option Two",
        "value": "two",
        "settings": {
            "template" : "_layouts/complicated.twig",
            "fizz": false
        }
    }] %}

{{ fieldOptions | json_encode }}

```

### Configuration with Twig inside `.json`

[](#configuration-with-twig-inside-json)

e.g. **field-config.json**

```
[
    {
        "label": "Option One",
        "value": "one",
        "settings": {
            "template" : "_layouts/basic.twig",
            "fizz": true
        }
    }
    {% if element.section != 'blog' %}
        ,{
            "label": "Option Two",
            "value": "two",
            "settings": {
                "template" : "_layouts/complicated.twig",
                "fizz": false
            }
        }
    {% endif %}
]

```

### Other less sane adventureous methods of configuration

[](#other-less-sane-adventureous-methods-of-configuration)

Using `.twig` as a router that points to regular static `.json` files using the Twig [source function](https://twig.symfony.com/doc/3.x/functions/source.html)

e.g. **layout-field-router.twig**

```
{% set section = element.owner.section ?? element.section ?? 'default' %}
{{ source("_config/layout-#{section}.json") }}

```

---

Alternatively, you could use a `.json` file that includes common elements from a `.twig` file using the Twig [block function](https://twig.symfony.com/doc/3.x/functions/block.html)

e.g. **field-config.json**

```
[
    {
        "label": "Option One",
        "value": "one",
        "virtuals": [
            {{ block( 'align', '_config/field-inputs.twig' ) }},
            {{ block( 'size',  '_config/field-inputs.twig' ) }},
        ]
    }
   ,{
        "label": "Option Two",
        "value": "two",
        "virtuals": [
            {{ block( 'align', '_config/field-inputs.twig' ) }},
            {{ block( 'size',  '_config/field-inputs.twig' ) }},
        ]
    }
]

```

.. and **field-inputs.twig**

```
{% block align %}
    {
        "label": "Alignment",
        "name" : "align",
        "type" : "select",
        "value": "text-left",
        "options": [
            "text-left"  : "Left",
            "text-center": "Center",
            "text-right" : "Right"
        ]
    }
{% endblock %}

{% block size %}
    {
        "label": "Font Size",
        "name" : "fontSize",
        "type" : "select",
        "value": "text-base",
        "options": [
            "text-xs"  : "Extra Small",
            "text-sm"  : "Small",
            "text-base": "Normal",
            "text-lg"  : "Large",
            "text-xl"  : "Extra Large"
        ]
    }
{% endblock %}

```

Element Variables
-----------------

[](#element-variables)

```
    'name'    => $element->type->name    ?? null,
    'type'    => $element->type->handle  ?? null,
    'field'   => $element->field->handle ?? null,
    'element' => $element->elementType   ?? null,
    'owner'   => [
        'site'    => $owner->site->handle    ?? null,
        'type'    => $owner->type->handle    ?? null,
        'level'   => $owner->level           ?? null,
        'section' => $owner->section->handle ?? null,
        'element' => $owner->elementType     ?? null,
    ],

```

Button-Only mode
----------------

[](#button-only-mode)

It is also possible to tell a MetaSettings field to operate in **Button Only** mode where if can be configured with a single "option" with multiple virtual input fields which can be accessed by clicking on a button.

The button uses the `label` from the single `` as its text.

Additionally, to differentiate between regular Select fields with one option and button-only fields `"type":"button"` must be included in the JSON config for the field like so:

```
[{
    "label": "Button Only Field Name",
    "value": "anything-really",
    "type" : "button",
    "tooltips": {...},
    "settings": {...},
    "virtuals": [{...}, {...}, {...}],
}]

```

It is not necessary to include a value for the `type` key for non-button-only fields.

Credits
-------

[](#credits)

Brought to you by [simplicate.ca](https://simplicate.ca)

Thanks to the [Design Tokens](https://plugins.craftcms.com/designtokens?craft5) field by Trendy Minds and the [Matrix Field Preview](https://plugins.craftcms.com/matrix-field-preview?craft5) plugin by Feral for inspiration.

[Bug reports welcome](https://github.com/simplicateca/craft-meta-settings-field/issues).

###  Health Score

45

—

FairBetter than 93% of packages

Maintenance87

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~57 days

Recently: every ~94 days

Total

20

Last Release

139d ago

Major Versions

0.4 → 1.0.0-beta2023-11-30

1.0.1-beta → v4.0.0-beta2024-02-15

v4.0.2-beta → 5.0.0-beta2024-04-27

### Community

Maintainers

![](https://www.gravatar.com/avatar/04feabe85950a47121653f8b5f37a4e9a96fdec0ff9d0e2e538ff0ed4b766aa3?d=identicon)[stevecomrie](/maintainers/stevecomrie)

---

Top Contributors

[![stevecomrie](https://avatars.githubusercontent.com/u/684903?v=4)](https://github.com/stevecomrie "stevecomrie (18 commits)")

---

Tags

craft-plugincraftcmscraftcms5dropdownselectcustom fieldcraft cmsselect-field

### Embed Badge

![Health badge](/badges/simplicateca-metasettings/health.svg)

```
[![Health](https://phpackages.com/badges/simplicateca-metasettings/health.svg)](https://phpackages.com/packages/simplicateca-metasettings)
```

###  Alternatives

[snapappointments/bootstrap-select

The jQuery plugin that brings select elements into the 21st century with intuitive multiselection, searching, and much more. Now with Bootstrap 4 support.

9.8k472.9k3](/packages/snapappointments-bootstrap-select)[kartik-v/dependent-dropdown

A multi level dependent dropdown JQuery plugin that allows nested dependencies.

1844.9M3](/packages/kartik-v-dependent-dropdown)[harvesthq/chosen

Chosen is a JavaScript plugin that makes select boxes user-friendly. It is currently available in both jQuery and Prototype flavors.

385.1M9](/packages/harvesthq-chosen)[henzeb/enumhancer

Your framework-agnostic Swiss Army knife for PHP 8.1+ native enums

68272.0k2](/packages/henzeb-enumhancer)[jjj/chosen

Chosen is a JavaScript plugin that makes select boxes user-friendly. It is currently available in both jQuery and Prototype flavors.

27494.7k2](/packages/jjj-chosen)[drpshtiwan/livewire-async-select

A powerful async select component for Laravel Livewire with Alpine.js - a modern alternative to Select2

1052.7k](/packages/drpshtiwan-livewire-async-select)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
