From 7266d8b1cbf4d7aa09fbbc62fc8c1252fcae9dc1 Mon Sep 17 00:00:00 2001
From: Marco Rieser <marco@rieser.dev>
Date: Wed, 10 Jun 2026 12:45:24 +0200
Subject: [PATCH 1/2] Add docs for namespaced tags

---
 content/collections/pages/building-a-tag.md   | 45 +++++++++++++++++++
 .../collections/pages/building-an-addon.md    |  9 ++++
 2 files changed, 54 insertions(+)

diff --git a/content/collections/pages/building-a-tag.md b/content/collections/pages/building-a-tag.md
index 93cba3302..9879962a4 100644
--- a/content/collections/pages/building-a-tag.md
+++ b/content/collections/pages/building-a-tag.md
@@ -202,6 +202,51 @@ You may choose to create aliases for your tag too. It will then be usable by its
 protected static $aliases = ['sample'];
 ```
 
+## Namespaced Tags
+
+Tags can be registered under a namespace to avoid handle collisions between addons. Without namespacing, if two addons register a tag with the same handle, the last one registered wins.
+
+### Enabling namespacing in an addon
+
+Set the `$tagNamespace` property on your addon's service provider. All tags registered by that addon will be callable under that namespace.
+
+```php
+class ServiceProvider extends AddonServiceProvider
+{
+    protected $tagNamespace = 'juicebox';
+}
+```
+
+::tabs
+
+::tab antlers
+```antlers
+{{ juicebox::my_tag:method }}
+```
+::tab blade
+```blade
+<s:juicebox::my_tag:method />
+```
+::
+
+When using the [fluent tag syntax](/blade#using-fluent-tags-with-blade), include the namespace:
+
+```php
+Statamic::tag('juicebox::my_tag:method')->fetch();
+```
+
+### Manual registration with a namespace
+
+You can also register a single tag class under a namespace directly:
+
+```php
+MyTag::register('juicebox');
+```
+
+:::tip
+Namespacing is opt-in. Addons without `$tagNamespace` continue to work exactly as before. Tags can still be called without the namespace if there is no collision.
+:::
+
 ## Parameters
 
 You may get the values of parameters through the `parameters` property.
diff --git a/content/collections/pages/building-an-addon.md b/content/collections/pages/building-an-addon.md
index 79b61e24f..70f778db7 100644
--- a/content/collections/pages/building-an-addon.md
+++ b/content/collections/pages/building-an-addon.md
@@ -234,6 +234,15 @@ protected $commands = [
 ];
 ```
 
+To avoid tag handle collisions with other addons, you can register all your tags under a namespace by setting `$tagNamespace` on your service provider:
+
+``` php
+protected $tagNamespace = 'your-addon-slug';
+```
+
+Tags will then be callable as `{{ your-addon-slug::tag_name }}`. See [Namespaced Tags](/building-a-tag#namespaced-tags) for full details.
+
+
 ## Assets
 
 ### CSS and Javascript

From 768352cc66e83433037970b7608c3af53bcd4724 Mon Sep 17 00:00:00 2001
From: Marco Rieser <marco@rieser.dev>
Date: Wed, 10 Jun 2026 12:48:08 +0200
Subject: [PATCH 2/2] Update examples to use `my-addon` as tag namespace in
 docs

---
 content/collections/pages/building-a-tag.md    | 10 +++++-----
 content/collections/pages/building-an-addon.md |  4 ++--
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/content/collections/pages/building-a-tag.md b/content/collections/pages/building-a-tag.md
index 9879962a4..a6564f3e3 100644
--- a/content/collections/pages/building-a-tag.md
+++ b/content/collections/pages/building-a-tag.md
@@ -213,7 +213,7 @@ Set the `$tagNamespace` property on your addon's service provider. All tags regi
 ```php
 class ServiceProvider extends AddonServiceProvider
 {
-    protected $tagNamespace = 'juicebox';
+    protected $tagNamespace = 'my-addon';
 }
 ```
 
@@ -221,18 +221,18 @@ class ServiceProvider extends AddonServiceProvider
 
 ::tab antlers
 ```antlers
-{{ juicebox::my_tag:method }}
+{{ my-addon::my_tag:method }}
 ```
 ::tab blade
 ```blade
-<s:juicebox::my_tag:method />
+<s:my-addon::my_tag:method />
 ```
 ::
 
 When using the [fluent tag syntax](/blade#using-fluent-tags-with-blade), include the namespace:
 
 ```php
-Statamic::tag('juicebox::my_tag:method')->fetch();
+Statamic::tag('my-addon::my_tag:method')->fetch();
 ```
 
 ### Manual registration with a namespace
@@ -240,7 +240,7 @@ Statamic::tag('juicebox::my_tag:method')->fetch();
 You can also register a single tag class under a namespace directly:
 
 ```php
-MyTag::register('juicebox');
+MyTag::register('my-addon');
 ```
 
 :::tip
diff --git a/content/collections/pages/building-an-addon.md b/content/collections/pages/building-an-addon.md
index 70f778db7..93638535d 100644
--- a/content/collections/pages/building-an-addon.md
+++ b/content/collections/pages/building-an-addon.md
@@ -237,10 +237,10 @@ protected $commands = [
 To avoid tag handle collisions with other addons, you can register all your tags under a namespace by setting `$tagNamespace` on your service provider:
 
 ``` php
-protected $tagNamespace = 'your-addon-slug';
+protected $tagNamespace = 'my-addon';
 ```
 
-Tags will then be callable as `{{ your-addon-slug::tag_name }}`. See [Namespaced Tags](/building-a-tag#namespaced-tags) for full details.
+Tags will then be callable as `{{ my-addon::tag_name }}`. See [Namespaced Tags](/building-a-tag#namespaced-tags) for full details.
 
 
 ## Assets