Skip to content

[Icons] Docs: Merging HTML and Twig syntaxes #2795

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: 2.x
Choose a base branch
from
Open

[Icons] Docs: Merging HTML and Twig syntaxes #2795

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1460cd2
[Icons] Docs: Cleanup of symfony/ux-twig-component
ThomasLandauer May 29, 2025
8f4ff4d
Update index.rst
ThomasLandauer May 29, 2025
b954ff7
Update index.rst
ThomasLandauer May 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 23 additions & 82 deletions src/Icons/doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,29 +59,37 @@ refers to the icons located in the ``header`` directory.
Loading Icons
-------------

.. code-block:: twig
To include an icon in your template, two syntaxes are available.

{# includes the contents of the 'assets/icons/user-profile.svg' file in the template #}
{{ ux_icon('user-profile') }}
.. tip::

{# icons stored in subdirectories must use the 'subdirectory_name:file_name' syntax
(e.g. this includes 'assets/icons/admin/user-profile.svg') #}
{{ ux_icon('admin:user-profile') }}
To use the HTML syntax, you need the ``symfony/ux-twig-component`` package:

{# this downloads the 'user-solid.svg' icon from the 'Flowbite' icon set via ux.symfony.com
and embeds the downloaded SVG contents in the template #}
{{ ux_icon('flowbite:user-solid') }}
.. code-block:: terminal

$ composer require symfony/ux-twig-component

The ``ux_icon()`` function defines a second optional argument where you can
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For both the Twig function and the HTML syntax, I think better to explain the first argument properly before jumping into customization.

It follows UX* rules: start simple, then show how to tweak things.. That way, users arent overwhelmed and can follow along more easily.

So I'd move back the CSS / height / etc. examples after the Flowbite one.

  • the science field, not the repository^^

define the HTML attributes added to the ``<svg>`` element:

.. code-block:: html+twig

{{ ux_icon('user-profile', {class: 'w-4 h-4'}) }}
{# renders <svg class="w-4 h-4"> ... </svg> #}
{# Includes the contents of 'assets/icons/user-profile.svg' in the template: #}
{{ ux_icon('user-profile') }}
{# Same in alternative HTML syntax: #}
<twig:ux:icon name="user-profile" />

{{ ux_icon('user-profile', {height: '16px', width: '16px', 'aria-hidden': true}) }}
{# renders <svg height="16" width="16" aria-hidden="true"> ... </svg> #}
{# Includes 'assets/icons/admin/user-profile.svg': #}
{{ ux_icon('admin:user-profile') }}
<twig:ux:icon name="admin:user-profile" />

{# Adding a CSS class or other attribute to the `<svg>` element: #}
{{ ux_icon('user-profile', {class: 'w-4', 'aria-hidden': 'true' }) }}
<twig:ux:icon name="user-profile" class="w-4" aria-hidden="true" />

{# Download the 'user-solid.svg' icon from the 'Flowbite' icon set via ux.symfony.com: #}
{{ ux_icon('flowbite:user-solid') }}
<twig:ux:icon name="flowbite:user-solid" />
Comment on lines +75 to +90
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reason for not mixing them like this is that some users might be confused about which syntax to use, and whether the HTML shown is the generated output

I really don’t think mixing the syntaxes in the first paragraph is a good idea: it doesn’t help clarify anything or solve any actual problem.


You can set default attributes for all icons in your `Configuration`_.


Icon Sets
Expand Down Expand Up @@ -170,30 +178,6 @@ icons in the "Tabler Icons" set, use the following command:
Page 1/3. Continue? (yes/no) [yes]:
>

HTML Syntax
~~~~~~~~~~~

In addition to the ``ux_icon()`` function explained in the previous sections,
this package also supports an alternative HTML syntax based on the ``<twig:ux:icon>``
tag if the ``symfony/ux-twig-component`` package is installed:

.. code-block:: html

<!-- renders "user-profile.svg" -->
<twig:ux:icon name="user-profile" class="w-4 h-4" />
<!-- renders "admin/user-profile.svg" -->
<twig:ux:icon name="admin:user-profile" class="w-4 h-4" />
<!-- renders 'user-solid.svg' icon from 'Flowbite' icon set via ux.symfony.com -->
<twig:ux:icon name="flowbite:user-solid" />

<!-- you can also add any HTML attributes -->
<twig:ux:icon name="user-profile" height="16" width="16" aria-hidden="true" />

.. tip::

To use the HTML syntax, the ``symfony/ux-twig-component`` package must be
installed in your project.

Downloading Icons
-----------------

Expand Down Expand Up @@ -314,49 +298,6 @@ Rendering Icons
and embeds the downloaded SVG contents in the template #}
{{ ux_icon('flowbite:user-solid') }}

HTML Syntax
~~~~~~~~~~~

.. code-block:: html+twig

<twig:ux:icon name="user-profile" />

{# Renders "user-profile.svg" #}
<twig:ux:icon name="user-profile" class="w-4 h-4" />

{# Renders "sub-dir/user-profile.svg" (sub-directory) #}
<twig:ux:icon name="sub-dir:user-profile" class="w-4 h-4" />

{# Renders "flowbite:user-solid" from ux.symfony.com #}
<twig:ux:icon name="flowbite:user-solid" />

.. note::

``symfony/ux-twig-component`` is required to use the HTML syntax.

Default Attributes
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer we keep this section.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I shortened it to one sentence here:

ux/src/Icons/doc/index.rst

Line 92 in b954ff7

You can set default attributes for all icons in your `Configuration`_.

Together with the explanation in the config section at https://symfony.com/bundles/ux-icons/current/index.html#full-configuration I think it's clear how this works.

Which part would you say is important to keep?

Copy link
Member

@kbond kbond May 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the clear example. A single sentence would get lost.

I guess I'm not understanding your motivation here. Why are you suggesting removing this section but not Icon Aliases below?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A single sentence would get lost.

Well, yes and no. I you merge everything I'm suggesting, then the page is only half as long ;-)
And if you start expanding the not-so-important parts (like this one), you need to expand/repeat the real important parts too...

And it's still shown twice: In the text, and in the config codeblock.

Why are you suggesting removing this section but not Icon Aliases below?

Mainly cause I haven't looked into it ;-)
And cause I don't understand that feature - so I thought I'd better not touch it...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the shortest documentation a goal we have?

Configuring default attributes is a question we had a lot of times, so dedicating some example was decided. It's not only luck or randomness that did drive every choice here 😅

~~~~~~~~~~~~~~~~~~

You can set default attributes for all icons in your configuration. These attributes will be
added to all icons unless overridden by the second argument of the ``ux_icon`` function.

.. code-block:: yaml

# config/packages/ux_icons.yaml
ux_icons:
default_icon_attributes:
fill: currentColor

Now, all icons will have the ``fill`` attribute set to ``currentColor`` by default.

.. code-block:: twig

# renders "user-profile.svg" with fill="currentColor"
{{ ux_icon('user-profile') }}

# renders "user-profile.svg" with fill="red"
{{ ux_icon('user-profile', {fill: 'red'}) }}

Icon Aliases
~~~~~~~~~~~~

Expand Down