create-addon

Create Statamic Addon Component

Scaffold Statamic extension points — custom tags, modifiers, fieldtypes, actions, scopes, and more — with correct boilerplate and registration.

Workflow

1. Determine Extension Type

Identify what the user wants to create:

Type	Directory	Base Class	Template Tag
Tag	app/Tags/	Statamic\Tags\Tags	{{ my_tag }}
Modifier	app/Modifiers/	Statamic\Modifiers\Modifier	{{ value | my_mod }}
Fieldtype	app/Fieldtypes/	Statamic\Fields\Fieldtype	CP field
Action	app/Actions/	Statamic\Actions\Action	CP bulk action
Scope	app/Scopes/	Statamic\Query\Scopes\Scope	query_scope="name"
Filter	app/Scopes/Filters/	Statamic\Query\Scopes\Filter	CP filter
Widget	app/Widgets/	Statamic\Widgets\Widget	CP dashboard
Dictionary	app/Dictionaries/	Statamic\Dictionaries\BasicDictionary	Dictionary fieldtype

All directories under app/ are auto-registered by Statamic — no manual service provider registration needed for project-level extensions.

2. Generate the PHP Class

Custom Tag

<?php

namespace App\Tags;

use Statamic\Tags\Tags;

class {ClassName} extends Tags
{
    /**
     * {{ {tag_name} }}
     */
    public function index()
    {
        // Return a string for single values
        // Return an array for tag pairs (loops)
        return [];
    }

    /**
     * {{ {tag_name}:{method} }}
     */
    public function {methodName}()
    {
        return [];
    }

    /**
     * {{ {tag_name}:* }}
     */
    public function wildcard($method)
    {
        return "Called: {$method}";
    }
}

Key tag patterns:

• $this->params->get('key', 'default') — access tag parameters
• $this->context->get('key') — access template context/cascade
• $this->isPair — check if used as tag pair
• $this->content — get content between tag pair
• Return string for output, array for loopable data

Custom Modifier

<?php

namespace App\Modifiers;

use Statamic\Modifiers\Modifier;

class {ClassName} extends Modifier
{
    /**
     * {{ value | {modifier_name}:param1:param2 }}
     */
    public function index($value, $params, $context)
    {
        return $value;
    }
}

Parameters:

• $value — the value being modified
• $params — array of colon-separated parameters
• $context — full template context array

Custom Fieldtype

<?php

namespace App\Fieldtypes;

use Statamic\Fields\Fieldtype;

class {ClassName} extends Fieldtype
{
    protected $icon = '{icon}';
    public $categories = ['{category}'];

    protected function configFieldItems(): array
    {
        return [
            'option_name' => [
                'display' => 'Option Label',
                'instructions' => 'Help text for this option.',
                'type' => 'select',
                'options' => [
                    'value1' => 'Label 1',
                    'value2' => 'Label 2',
                ],
                'default' => 'value1',
            ],
        ];
    }

    public function preProcess($value)
    {
        // Transform value before sending to Vue component
        return $value;
    }

    public function process($value)
    {
        // Transform value before saving to file
        return $value;
    }

    public function augment($value)
    {
        // Transform value for template rendering
        return $value;
    }
}

Custom Action

<?php

namespace App\Actions;

use Statamic\Actions\Action;

class {ClassName} extends Action
{
    public static function title()
    {
        return '{Title}';
    }

    public function visibleTo($item)
    {
        return $item instanceof \Statamic\Entries\Entry;
    }

    public function authorize($user, $item)
    {
        return $user->can('edit', $item);
    }

    public function run($items, $values)
    {
        foreach ($items as $item) {
            // Perform action on each item
        }

        return trans_choice('{count} item processed|{count} items processed', $items->count());
    }
}

Custom Query Scope

<?php

namespace App\Scopes;

use Statamic\Query\Scopes\Scope;

class {ClassName} extends Scope
{
    public function apply($query, $values)
    {
        $query->where('{field}', '{value}');
    }
}

Usage in templates: {{ collection:blog query_scope="{scope_name}" }}

Custom Widget

<?php

namespace App\Widgets;

use Statamic\Widgets\Widget;

class {ClassName} extends Widget
{
    public function html()
    {
        return view('{view_name}', [
            'data' => $this->config('data_source', 'default'),
        ]);
    }
}

3. Naming Conventions

• Class name: StudlyCase (e.g., EventList, ReadTime)
• Tag handle: snake_case of class name (e.g., {{ event_list }})
• Modifier handle: snake_case of class name (e.g., {{ value | read_time }})
• Fieldtype handle: snake_case of class name (e.g., toggle_password)
• Scope handle: snake_case for template use (e.g., query_scope="featured")

4. Create the File

Write the PHP class to the correct auto-registered directory. Verify the directory exists first:

mkdir -p app/{Type}s

5. Vue Component (Fieldtypes Only)

For custom fieldtypes, create a Vue 3 component using Composition API:

<script setup>
import { Fieldtype } from '@statamic/cms';

const emit = defineEmits(Fieldtype.emits);
const props = defineProps(Fieldtype.props);
const { expose, update, meta } = Fieldtype.use(emit, props);

defineExpose(expose);
</script>

<template>
  <div>
    <input :value="props.value" @input="update($event.target.value)" />
  </div>
</template>

Register in addon JS: Statamic.$components.register('{handle}-fieldtype', Component);

6. Summary

After creating the extension, display:

• File path of the created class
• How to use it (template tag syntax, modifier syntax, etc.)
• Reminder that app/ directory extensions are auto-registered
• For addon packages: mention php please make:addon for full scaffold

Full Addon Package

For a distributable addon package (not just a project-level extension), use:

php please make:addon vendor/package-name

This creates a full scaffold in addons/vendor/package-name/ with:

• ServiceProvider extending AddonServiceProvider
• composer.json with auto-discovery
• Standard directory structure for all extension types

Register extensions in the service provider's protected arrays: $tags, $modifiers, $fieldtypes, $widgets, $commands, $routes, $vite.