README

ACF SVG Icon Picker Field

Add a field type to ACF for selecting SVG icons from a popup modal. Theme developers can provide a set of SVG icons to choose from.

Compatibility

This ACF field type is compatible with:

ACF 6
ACF 5

Screenshots

Installation

via Composer

Run composer require smithfield-studio/acf-svg-icon-picker and activate the plugin via the plugins admin page.

Manually

Copy the acf-svg-icon-picker folder into your wp-content/plugins folder
Activate the plugin
Create a new ACF field and select the SVG Icon Picker type

Switch from the legacy 'ACF Icon Picker' to 'ACF SVG Icon Picker'

If you're coming from the original ACF Icon Picker plugin, you can switch to this plugin by following these steps:

Deactivate the old ACF Icon Picker plugin
Install the ACF SVG Icon Picker plugin via Composer or manually
Activate the ACF SVG Icon Picker plugin
Configure your desired icon path via the new filters. Remove any old filters in use: acf_icon_path, acf_icon_url or acf_icon_path_suffix.
Go over your field configurations and change the field type from icon-picker to svg_icon_picker in the field settings. Be aware of the underscores in the field type name.
Check if the field type is now available in your ACF field settings

Usage of this plugin

We recommend storing your SVG icons in a folder within your theme. This plugin defaults to looking for icons inside the icons/ folder of your theme. You can change this path by using the acf_svg_icon_picker_folder filter.

When using this plugin in conjunction with a parent/child theme, you can store your icons in the parent theme and use the child theme to override the path to the icons. This way, you can provide a set of icons in the parent theme and still allow the child theme to override them.

You can configure this field to output the icon name or the icon SVG markup. You can set this in the field settings by changing the return_format.

Helper functions

We provide helper functions to fetch icons from the theme folder, without it mattering if the icon is stored in the parent or child theme.

use function SmithfieldStudio\AcfSvgIconPicker\get_svg_icon_uri;
use function SmithfieldStudio\AcfSvgIconPicker\get_svg_icon_path;
use function SmithfieldStudio\AcfSvgIconPicker\get_svg_icon;

$my_icon_field = get_field('my_icon_field');

// Get the icon URL
$icon_url = get_svg_icon_uri($my_icon_field);

// Get the icon file system path
$icon_path = get_svg_icon_path($my_icon_field);

// Get the icon contents
$icon_svg = get_svg_icon($my_icon_field);

Filters

Use the below filters to override the default icon folder inside your theme.

// modify the path to the icons directory in your theme.
add_filter('acf_svg_icon_picker_folder', function () {
  return 'resources/icons/';
});

In case you do not want to store the icons in the theme folder, you can use the filter below to change the path to an icons directory in a custom location. In this example, the icons are stored in the WP_CONTENT_DIR . '/icons/' folder.

add_filter('acf_svg_icon_picker_custom_location', function () {
  return [
    'path' => WP_CONTENT_DIR . '/icons/',
    'url' =>  content_url() . '/icons/',
  ];
});

ACF Builder / ACF Composer

$fields->addField('my_icon', 'svg_icon_picker', [
    'label'         => 'My Icon',
    'return_format' => 'value', // or 'icon'
])

Changelog

See releases for the full changelog

4.1.0:
- feat: Add possebility to directly return the icon markup from the field by using the icon return format
- feat: Enhance markup of the icon picker modal and field.
- docs: Update hooks in readme to the correct ones by @huubl in #29
- test: Add tests for the new return format
- ci: Run PHPCS on PRs
4.0.1:
- Fix version numbers in constant.
- chore: Add files to export ignore
4.0.0:
- Remove/deprecate legacy filters, refactor and simplify icon path filters by @Levdbas in #25
- add unit tests, phpstan and return types by @Levdbas in #25
- add better support for hashed assets by @mike-sheppard in #26
3.1.4: Fix filter on filenames with diacritical marks by @Rvervuurt in #21
3.1.3: Added MutationObserver by @chrisbakr in #20
3.1.2: Add debounce to improve filter performance by @stefanmomm in #17
3.1.1: Optimize css by @stefanmomm in #16
3.1.0: Changed name of field to svg_icon_picker to avoid conflicts with vanilla ACF Icon Picker field.
3.0.0: Revert to original ACF field name, quick tidy + README updates
2.0.0: Fix for ACF 6.3 which now has an official icon-picker field + merged open PRs from @Levdbas in #38 & @phschmanau in #37

Forked from houke/acf-icon-picker

1.9.1: ACF 6 compatibility fix. Thanks to @idflood in #30
1.9.0: Fix issue with Gutenberg preview not updating when removing. Thanks to @cherbst in #23
1.8.0: Fix issue with Gutenberg not saving icon. Thanks to @tlewap in #17
1.7.0: 2 new filters for more control over icon path. Thanks to @benjibee in #11
1.6.0: Performance fix with lots of icons. Thanks to @idflood in #9
1.5.0: Fix issue where searching for icons would break preview if icon name has space
1.4.0: Add filter to change folder where svg icons are stored
1.3.0: Adding close option on modal
1.2.0: Adding search filter input to filter through icons by name
1.1.0: Add button to remove the selected icon when the field is not required
1.0.0: First release

smithfield-studio / acf-svg-icon-picker

Maintainers

Details