--- title: "Customize The Events Calendar Settings with the Tribe Settings API" source: "https://docs.nexcess.com/software/the-events-calendar/tribe-settings-api/" description: "If you're writing a custom add-on, a site-specific plugin, or a code snippet that extends The Events Calendar or Event Tickets, the Tribe Settings API gives you…" vertical: "Software" area: "The Events Calendar" date: "2019-10-18" last_modified: "2026-07-02" --- # Customize The Events Calendar Settings with the Tribe Settings API If you’re writing a custom add-on, a site-specific plugin, or a code snippet that extends [The Events Calendar](https://theeventscalendar.com/products/wordpress-events-calendar/) or [Event Tickets](https://theeventscalendar.com/products/wordpress-event-tickets/), the Tribe Settings API gives you a clean way to plug your own options into the existing settings screens – the same API our own tabs (General, Display, Integrations, etc.) are built on. Instead of reinventing a settings page with the WordPress Settings API, you can register a tab, add fields, and let Tribe Settings handle the rendering, validation, saving, and error messaging for you. The API was originally introduced in The Events Calendar 2.0.5 and has since been extracted into the shared [tribe-common](https://github.com/the-events-calendar/tribe-common) library (`@since 4.0.1`), where it is bootstrapped and loaded on every request for any plugin that embeds tribe-common (The Events Calendar, Event Tickets, and their add-ons). Four classes make up the API, and all four live in the */common/src/Tribe/* folder of the plugin. The older *Tribe\_\_Events\_\_\** class names still exist as deprecated shims under */common/src/deprecated/*, but new code should use the current class names listed below. ## How the four classes fit together Each class sits at a different level of abstraction. In practice you’ll usually only touch the last one: - **Tribe\_\_Settings** – the top-level controller. It owns the list of tabs, routes the current request to the right tab, and dispatches the full render / validate / save lifecycle. You rarely instantiate this yourself; it’s constructed by tribe-common. You *do* hook into its actions and filters to inject content. - **Tribe\_\_Field** – renders an individual field (text box, dropdown, toggle, etc.). You pass it an array describing the field and it outputs the HTML. Usable anywhere – settings, metaboxes, user profile screens – not just inside a tab. - **Tribe\_\_Validate** – validates and sanitizes a single field’s value based on a validation type (e.g. *url*, *positive\_int*, *email*). Also usable standalone, but in a settings tab it’s invoked automatically on save. - **Tribe\_\_Settings\_Tab** – the public API. Instantiating this class registers a new tab, its fields, and its defaults. It wires the other three classes together so you don’t have to. If you’re creating a new tab, *Tribe\_\_Settings\_Tab* is where you should focus. The other three are documented below for when you need to reach a level deeper – for example, rendering a single field in a metabox, adding a custom validation rule, or modifying what another plugin’s tab renders via hooks. ## Quick start: register a tab in ~20 lines A minimal working example that adds a *My Add-on* tab to the Events settings screen with a single text field. All fields in this example save as entries in the serialized *Tribe\_\_Main::OPTIONNAME* array, which is the same array the rest of The Events Calendar uses – you can read them back with `tribe_get_option( 'my_addon_api_key' )`. ``` add_action( 'tribe_settings_do_tabs', function () { $fields = [ 'my_addon_heading' => [ 'type' => 'heading', 'label' => __( 'My Add-on Settings', 'my-addon' ), ], 'my_addon_api_key' => [ 'type' => 'text', 'label' => __( 'API key', 'my-addon' ), 'tooltip' => __( 'Paste the API key from your dashboard.', 'my-addon' ), 'validation_type' => 'alpha_numeric_with_dashes_and_underscores', 'can_be_empty' => true, ], 'my_addon_enabled' => [ 'type' => 'toggle', 'label' => __( 'Enable integration', 'my-addon' ), 'default' => false, 'validation_type' => 'boolean', ], ]; new Tribe__Settings_Tab( 'my-addon', // Tab ID (used in the URL). __( 'My Add-on', 'my-addon' ), // Tab label. [ 'priority' => 55, // Places the tab between Licenses (40) and Help (60). 'fields' => $fields, ] ); } ); ``` The *tribe\_settings\_do\_tabs* action is the standard entry point for registering tabs – firing your *new Tribe\_\_Settings\_Tab()* call inside it ensures the tab is registered at the right moment in the lifecycle. See the [Priority](#h-priority) section below for how to position your tab relative to the existing ones. ## Class reference ### Class *Tribe\_\_Settings* - File: */common/src/Tribe/Settings.php* - Description: static helper class that allows registration of settings; instantiation takes place in tribe-common on the *tec\_settings\_init* action. - Deprecated alias: *Tribe\_\_Events\_\_Settings* (see */common/src/deprecated/Tribe\_\_Events\_\_Settings.php*). **Class variables:** - *$instance*: (stdClass) singleton method instance var - *$tabs*: (array) the tabs that will appear in the settings page (filtered on class construct) - *$fields*: (array) multidimensional array of the fields that will be generated for the entire settings panel, tabs are represented in the array keys - *$defaultTab*: (string) the default tab for the settings panel, this should be a tab ID - *$currentTab*: (string) the current tab being displayed - *$noSaveTabs*: (array) tabs that shouldn’t show the save button - *$adminSlug*: (string) the slug used in the admin to generate the settings page - *$menuName*: (string) the menu name used for the settings page - *$requiredCap*: (string) the required capability for the settings page - *$errors*: (mixed) errors that occur after a save operation - *$saved*: (bool) true when just saved - *$admin\_page*: (string) the *$current\_screen* name corresponding to the admin page - *$major\_error*: (bool) true if a major error that prevents saving occurred - *$validated*: (array) holds validated fields **Action Hooks:** Tribe\_\_Settings fires a large number of actions. They’re grouped below by when they run, so you can pick the right place to inject content or behavior. *Registration & page chrome (most common)* - *tribe\_settings\_do\_tabs*: register new tabs here (used with the *Tribe\_\_Settings\_Tab* class) - *tribe\_settings\_after\_do\_tabs*: occurs after all tabs are added - *tribe\_settings\_top*: occurs before opening *
* of the settings page - *tribe\_settings\_above\_tabs*: occurs right above the tabs (below the title) - *tribe\_settings\_below\_tabs*: occurs right below the tabs - *tribe\_settings\_below\_tabs\_tab\_{$currentTab}*: occurs right below the tabs for the specified tab - *tribe\_settings\_after\_tabs*: occurs after tabs - *tribe\_settings\_bottom*: occurs at the bottom of the settings screen *Form rendering* - *tribe\_settings\_above\_form\_element*: occurs above the form element - *tribe\_settings\_above\_form\_element\_tab\_{$currentTab}*: occurs above the form element for the specified tab - *tribe\_settings\_before\_content*: occurs after the form element - *tribe\_settings\_before\_content\_tab\_{$currentTab}*: occurs after the form element for the specified tab - *tribe\_settings\_content\_tab\_{$currentTab}*: generates the content for the specified tab - *tribe\_settings\_after\_content\_tab\_{$currentTab}*: occurs after the content for the specified tab - *tribe\_settings\_after\_content*: occurs after the content - *tribe\_settings\_after\_form\_element*: occurs after the form element - *tribe\_settings\_after\_form\_element\_tab\_{$currentTab}*: occurs after the form element for the specified tab - *tribe\_settings\_after\_form\_div*: occurs after the closing form div *Validation & save* - *tribe\_settings\_validate\_before\_checks*: occurs during validation, before any kind of checks are made - *tribe\_settings\_validate*: occurs in validation once the permission, nonce and tab checks are made - *tribe\_settings\_validate\_tab\_{$currentTab}*: same as *tribe\_settings\_validate* but for a specific tab - *tribe\_settings\_validate\_field*: occurs on field validation - *tribe\_settings\_validate\_field\_{$field\_id}*: occurs on specific field validation - *tribe\_settings\_save*: occurs on save - *tribe\_settings\_save\_tab\_{$currentTab}*: occurs on save for specific tab - *tribe\_settings\_save\_field*: occurs on field save - *tribe\_settings\_save\_field\_{$field\_id}*: occurs on specific field save **Filter Hooks:** - *tribe\_settings\_menu\_name*: filter the settings panel’s menu name - *tribe\_settings\_req\_cap*: filter the required capability, defaults to *manage\_options* - *tribe\_settings\_admin\_slug*: filter the admin slug for the settings page - *tribe\_settings\_tabs*: filter the tabs for the settings panel - *tribe\_settings\_fields*: filter the fields for the settings panel - *tribe\_settings\_default\_tab*: filter the default tab, defaults to *general* - *tribe\_settings\_current\_tab*: filter the current tab, defaults to *$\_GET\[‘tab’\]* - *tribe\_settings\_no\_save\_tabs*: filter which tabs don’t have the save tab - *tribe\_settings\_form\_element*: filter the opening form element for the settings panel, defaults to *
* - *tribe\_settings\_closing\_form\_element*: filter the closing form element for the settings panel, defaults to *
* - *tribe\_settings\_validate\_field\_value*: filter a field’s value before we validate it - *tribe\_settings\_save\_field\_value*: filter a field’s value before we save it - *tribe\_settings\_save\_field\_parent\_option*: filter a field’s parent array option id before saving it - *tribe\_settings\_save\_option\_array*: filter an option array before saving it - *tribe\_settings\_display\_errors*: filter the *$errors* array before displaying it - *tribe\_settings\_count\_errors*: filter how many errors there are before displaying them - *tribe\_settings\_display\_errors\_or\_not*: determine whether to display errors or not, defaults to whether the error count is above zero or not - *tribe\_settings\_error\_message*: filter the full error message - *tribe\_settings\_success\_message*: filter the success message ### Class *Tribe\_\_Field* - File: */common/src/Tribe/Field.php* - Description: helper class that creates fields for use in Settings, MetaBoxes, Users, anywhere. Instantiate it whenever you need a field. - Deprecated alias: *Tribe\_\_Events\_\_Field* (see */common/src/deprecated/Tribe\_\_Events\_\_Field.php*). **Class variables:** - *$id*: (string) the field’s id - *$name*: (string) the field’s name (also known as its label) - *$args*: (array) the field’s arguments - *$defaults*: (array) field defaults (static) - *$valid\_field\_types*: (array) the valid field types **Constructor variables:** These variables are passed to the class when it is instantiated, like so: *new Tribe\_\_Field($id, $field, $value = null)* - *$id*: (string) the field’s id - *$field*: (array) the field object/arguments - *$value*: (mixed)\[optional\] the field’s current value **Field Arguments:** These are set with the *$args* variable. Below are the different arguments with their default value: - ‘type’ => ‘html’, the field type - ‘name’ => $id, the field’s name attribute (used in *$\_POST*) - ‘class’ => null, class to be applied to the field’s *
* element - ‘label’ => null, the field’s label - ‘tooltip’ => null, the field’s description/label, used in the tooltip as well as in the screen reader label - ‘size’ => ‘medium’, (possible values are small, medium or large) this applies to text, text area, dropdown, and license\_key fields only - ‘html’ => null, the html of a field (applies only to an html field) - ‘error’ => false, boolean to indicate if the field is currently erroneous or not – this is set via *Tribe\_\_Validate* - ‘value’ => $value, the current value for the field - ‘options’ => null, options for the field (this applies to radio and dropdown fields only) - ‘conditional’ => true, allows you to set a condition on a field to determine whether it should appear or not, you can pass a function, a variable, whatever you want here, but it expects a boolean value - ‘display\_callback’ => null, a function name to generate the field with, this would overwrite the class’ behaviour and generate the field with the specified function instead - ‘if\_empty’ => null, optional message to display for a radio or dropdown button when *$options* are empty, handy for dynamic fields - ‘can\_be\_empty’ => false, allows a field to be saved with an empty value - ‘clear\_after’ => true, to add a *
* after the field or not, defaults to add it **Valid Field Types:** - heading: an *

* wrapped heading - html: arbitrary html code - wrapped\_html: arbitrary html code with a wrapper element - text: regular text field - textarea: regular text area field - wysiwyg: rich text (TinyMCE) field - email: email text field - number: numeric input field - color: color-picker field - radio: radio buttons - checkbox\_bool: single checkbox (true or false) - checkbox\_list: checkbox list with options - toggle: on/off toggle switch - dropdown: regular *