diff --git a/html_sanitizer.rst b/html_sanitizer.rst
index f2400103284..b2b7a2cbee7 100644
--- a/html_sanitizer.rst
+++ b/html_sanitizer.rst
@@ -462,6 +462,80 @@ This can also be used to remove elements from the allow list.
->dropElement('figure')
);
+Default Action
+~~~~~~~~~~~~~~
+
+By default, unconfigured tags are dropped along with their children. If you would rather not lose all children elements by default, you can configure the default action to be ``Block``. Specific elements can still be dropped if needed.
+
+ .. code-block:: yaml
+
+ # config/packages/html_sanitizer.yaml
+ framework:
+ html_sanitizer:
+ sanitizers:
+ app.post_sanitizer:
+ # ...
+
+ # remove all tags by default, but process their children
+ default_action: 'block'
+ # remove and its children
+ drop_elements: ['figure']
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+ block
+
+
+ figure
+
+
+
+
+ .. code-block:: php
+
+ // config/packages/framework.php
+ use Symfony\Config\FrameworkConfig;
+
+ return static function (FrameworkConfig $framework): void {
+ $framework->htmlSanitizer()
+ ->sanitizer('app.post_sanitizer')
+ // remove all tags by default, but process their children
+ ->defaultAction('block')
+ // remove and its children
+ ->dropElement('figure')
+ ;
+ };
+
+ .. code-block:: php-standalone
+
+ use Symfony\Component\HtmlSanitizer\HtmlSanitizer;
+ use Symfony\Component\HtmlSanitizer\HtmlSanitizerAction;
+ use Symfony\Component\HtmlSanitizer\HtmlSanitizerConfig;
+
+ $postSanitizer = new HtmlSanitizer(
+ (new HtmlSanitizerConfig())
+ // remove all tags by default, but process their children
+ ->defaultAction(HtmlSanitizerAction::Block)
+ // remove and its children
+ ->dropElement('figure')
+ );
+
+.. note::
+
+ Configuring a default action of ``Allow`` will allow all tags but they will not have any attributes. You probably should still disallow at least ``script`` tags if you want to do this, but generally speaking using an explicit allowlist is going to be much safer.
+
Allow Attributes
~~~~~~~~~~~~~~~~