Skip to content

[Icons] Restructure documentation hierarchy #3494

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
makraz wants to merge 1 commit into
base: 3.x
Choose a base branch
from
Open

[Icons] Restructure documentation hierarchy #3494

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
115 changes: 47 additions & 68 deletions src/Icons/doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,33 +47,6 @@ where the icon is located, or a combination of both.
For example, the ``bi`` prefix refers to the Bootstrap Icons set, while the ``header`` prefix
refers to the icons located in the ``header`` directory.

Loading Icons
-------------

.. code-block:: twig

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

{# 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') }}

{# 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') }}

The ``ux_icon()`` function defines a second optional argument where you can
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> #}

{{ ux_icon('user-profile', {height: '16px', width: '16px', 'aria-hidden': true}) }}
{# renders <svg height="16" width="16" aria-hidden="true"> ... </svg> #}

Icon Sizes
~~~~~~~~~~

Expand Down Expand Up @@ -172,8 +145,8 @@ Icon Set Icons License Prefix Example
`Tabler Icons`_ 5200 MIT ``tabler`` ``tabler:check``
======================== ======= ========== =============== =====================

Search Icon sets
~~~~~~~~~~~~~~~~
Search Icon Sets
^^^^^^^^^^^^^^^^

You can use the ``ux:icons:search`` command to search for icon sets, or to find
the prefix of a specific icon set:
Expand All @@ -193,7 +166,7 @@ the prefix of a specific icon set:
php bin/console ux:icons:search tabler arrow

Search Icons
~~~~~~~~~~~~
^^^^^^^^^^^^

You can also search for icons within a specific icon set. To search for "arrow"
icons in the "Tabler Icons" set, use the following command:
Expand Down Expand Up @@ -222,33 +195,8 @@ 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 provides an alternative HTML-based syntax. Before using it,
ensure that the following package is installed in your application:

.. code-block:: terminal

$ composer require symfony/ux-twig-component

You can then use the following syntax to include icons::

.. 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" />

Downloading Icons
-----------------
Loading Icons
-------------

This package doesn't include any icons, but provides access to over 200,000
open source icons.
Expand Down Expand Up @@ -277,7 +225,7 @@ a subdirectory, the *name* will be ``subdirectory:icon_name``.
│ └─ ...
└─ ...

Icons On-Demand
On-Demand Icons
~~~~~~~~~~~~~~~

`ux.symfony.com/icons`_ has a huge searchable repository of icons from many
Expand All @@ -297,8 +245,8 @@ for future requests for the same icon.

`Local SVG Icons`_ of the same name will have precedence over *on-demand* icons.

Importing Icons
---------------
Imported Icons
~~~~~~~~~~~~~~

While *on-demand* icons are great during development, they require HTTP requests
to fetch the icon and always use the *latest version* of the icon. It's possible
Expand All @@ -323,7 +271,7 @@ the ``assets/icons/`` directory. You can think of importing an icon as *locking
Imported icons must be committed to your repository.

Locking On-Demand Icons
~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^

You can *lock* (import) all the *on-demand* icons you're using in your project by
running the following command:
Expand Down Expand Up @@ -354,6 +302,9 @@ the report to overwrite existing icons by using the ``--force`` option:
Rendering Icons
---------------

Twig Function
~~~~~~~~~~~~~

.. code-block:: twig

{# includes the contents of the 'assets/icons/user-profile.svg' file in the template #}
Expand All @@ -367,9 +318,42 @@ Rendering Icons
and embeds the downloaded SVG contents in the template #}
{{ ux_icon('flowbite:user-solid') }}

The ``ux_icon()`` function defines a second optional argument where you can
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> #}

{{ ux_icon('user-profile', {height: '16px', width: '16px', 'aria-hidden': true}) }}
{# renders <svg height="16" width="16" aria-hidden="true"> ... </svg> #}

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

In addition to the ``ux_icon()`` function explained in the previous sections,
this package also provides an alternative HTML-based syntax. Before using it,
ensure that the following package is installed in your application:

.. code-block:: terminal

$ composer require symfony/ux-twig-component

You can then use the following syntax to include icons::

.. 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" />

.. code-block:: html+twig

<twig:ux:icon name="user-profile" />
Expand All @@ -387,8 +371,6 @@ HTML Syntax

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

.. _icons_default_attributes:

Default Attributes
~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -568,11 +550,8 @@ Performance
The UX Icons component is designed to be fast. The following are some of
the optimizations made to ensure the best performance possible.

Caching
-------

On-Demand VS Import
^^^^^^^^^^^^^^^^^^^
On-Demand vs Import
~~~~~~~~~~~~~~~~~~~

While *on-demand* icons are great during development, they require HTTP requests to fetch the icon
and always use the *latest version* of the icon. It's possible the icon could change or be removed
Expand Down