Ngày 24/7 vừa qua, team WordPress Core đã công bố dev notes chi tiết về một trong những tính năng đáng chú ý nhất của WordPress 7.1: SVG Icons API. Nếu ở bản 7.0, WordPress chỉ có sẵn một bộ icon cố định dùng trong block editor, thì nay bạn có thể đăng ký icon riêng, gom thành bộ sưu tập, render bằng PHP, và truy xuất qua REST API.
Trong bài này, mình sẽ hướng dẫn từng bước cách tạo icon collection, đăng ký custom icons, render trong theme, và kết nối với block editor. Toàn bộ code mẫu áp dụng cho WordPress 7.1 Beta 3 trở lên, chính thức ra mắt 19/8 tới.
SVG Icons API Trong WordPress 7.1 La Gi?
SVG Icons API là hệ thống quản lý icon tập trung mới của WordPress. Thay vì mỗi plugin tự nhúng SVG vào code theo cách riêng, nay tất cả đi qua một API chung: đăng ký ở một chỗ, dùng ở nhiều nơi — block editor, REST API, PHP template.
Ở WordPress 7.0, core đã có sẵn bộ icon tên core dùng cho Icon block trong editor. Nhưng đó chỉ là internal API, developer không thể thêm icon riêng vào bộ picker. Bản 7.1 nâng cấp thành public API đầy đủ, cho phép plugin và theme đăng ký icon collection riêng, icon xuất hiện ngay trong block editor picker.
Tai Sao Developer Nen Dung SVG Icons API?
Trước đây, nếu muốn thêm icon vào plugin, developer thường phải tự nhúng SVG trực tiếp vào HTML, dùng Dashicons (font icon cũ), hoặc phụ thuộc thư viện bên thứ ba như Font Awesome. Cách này gây ra ba vấn đề: SVG rải rác khó quản lý, không tái sử dụng được giữa frontend và editor, và dễ dẫn đến lỗ hổng XSS nếu không sanitize kỹ.
SVG Icons API giải quyết cả ba. Icon đăng ký một lần, sanitize tự động qua wp_kses với allowlist khắt khe (chỉ cho phép svg, path, polygon), và có thể gọi ở bất kỳ đâu — PHP template, block editor, hay REST API endpoint.
BUOC 1: Tao Icon Collection Cho Plugin Hoac Theme
Mỗi icon phải thuộc về một collection. Collection đóng vai trò namespace, giúp icon từ các nguồn khác nhau không bị trùng tên. Ví dụ: core/plus khác my-plugin/plus.
Đầu tiên, đăng ký collection bằng wp_register_icon_collection() trên hook init:
function my_plugin_register_icon_collection() {
wp_register_icon_collection(
'my-plugin',
array(
'label' => __( 'My Plugin Icons', 'my-plugin' ),
'description' => __( 'Bo icon cho My Plugin.', 'my-plugin' ),
)
);
}
add_action( 'init', 'my_plugin_register_icon_collection' );Quy tắc đặt tên collection: chỉ dùng chữ thường, số, dấu gạch ngang, và dấu gạch dưới. Phải bắt đầu và kết thúc bằng chữ cái hoặc số. WordPress mặc định đăng ký sẵn collection core với bộ icon tích hợp.
Nếu muốn gỡ collection (ví dụ khi deactivate plugin), dùng wp_unregister_icon_collection() ở priority cao hơn:
function my_plugin_unregister_icon_collection() {
wp_unregister_icon_collection( 'my-plugin' );
}
add_action( 'init', 'my_plugin_unregister_icon_collection', 20 );Khi gỡ collection, toàn bộ icon trong đó cũng bị xóa theo. Không cần gỡ từng icon thủ công.
BUOC 2: Dang Ky Custom Icons Vao Collection
Sau khi có collection, đăng ký từng icon bằng wp_register_icon(). Có hai cách cung cấp SVG: inline string hoặc đường dẫn file.
Cách 1: Inline SVG string — phù hợp icon đơn giản, ít element:
wp_register_icon(
'my-plugin/star',
array(
'label' => __( 'Star', 'my-plugin' ),
'content' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2l2.9 6.9 7.1.6-5.4 4.7 1.6 7L12 18l-6.2 3.2 1.6-7L2 9.5l7.1-.6z" /></svg>',
)
);Cách 2: File SVG riêng biệt — phù hợp icon phức tạp, muốn tách file:
wp_register_icon(
'my-plugin/heart',
array(
'label' => __( 'Heart', 'my-plugin' ),
'file_path' => plugin_dir_path( __FILE__ ) . 'icons/heart.svg',
)
);Một lưu ý quan trọng: file_path được đọc lazy — file không mở lúc đăng ký, chỉ mở khi icon thực sự cần render. Nghĩa là nếu đường dẫn sai, đăng ký vẫn thành công nhưng khi render sẽ trả content rỗng. Hãy chắc chắn path đúng trên môi trường chạy thực tế.
Code hoàn chỉnh đăng ký collection và icons:
function my_plugin_register_icons() {
// Dang ky collection truoc
wp_register_icon_collection(
'my-plugin',
array(
'label' => __( 'My Plugin Icons', 'my-plugin' ),
)
);
// Icon tu inline SVG
wp_register_icon(
'my-plugin/star',
array(
'label' => __( 'Star', 'my-plugin' ),
'content' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2l2.9 6.9 7.1.6-5.4 4.7 1.6 7L12 18l-6.2 3.2 1.6-7L2 9.5l7.1-.6z" /></svg>',
)
);
// Icon tu file SVG
wp_register_icon(
'my-plugin/heart',
array(
'label' => __( 'Heart', 'my-plugin' ),
'file_path' => plugin_dir_path( __FILE__ ) . 'icons/heart.svg',
)
);
}
add_action( 'init', 'my_plugin_register_icons' );SVG Sanitization Hoat Dong Nhu The Nao?
WordPress tự động sanitize mọi SVG thông qua wp_kses với allowlist rất保守. Chỉ ba element được phép: <svg>, <path>, và <polygon>. Mỗi element chỉ giữ một tập attribute cố định. Mọi thứ ngoài allowlist — inline style, script, event handler, element khác như <rect> hay <circle> — đều bị strip.
Điều này có nghĩa: nếu icon của bạn dùng <circle> hoặc <rect>, nó sẽ không hiển thị đúng. Giải pháp tạm thời là convert sang <path> bằng công cụ như SVGOMG hoặc Figma export. Team WordPress đang mở rộng allowlist trong tương lai, nhưng ở 7.1 vẫn giới hạn ba element trên.
BUOC 3: Render Icon Trong PHP Template
Sau khi đăng ký, render icon bất cứ đâu trong theme bằng wp_get_icon(). Hàm này trả về SVG markup sẵn sàng in ra:
// Icon co ban, size mac dinh 24px
echo wp_get_icon( 'core/plus' );
// Icon voi size, label, va class tuy chinh
echo wp_get_icon(
'my-plugin/star',
array(
'size' => 32,
'label' => __( 'Noi bat', 'my-plugin' ),
'class' => 'my-plugin-star',
)
);
// Icon lam link
echo '<a href="' . esc_url( $url ) . '">' . wp_get_icon( 'my-plugin/heart' ) . '</a>';Tham số label nếu có sẽ trở thành aria-label của SVG, giúp accessibility. Nếu không truyền label, SVG sẽ có aria-hidden="true" để screen reader bỏ qua — phù hợp icon trang trí.
BUOC 4: Hien Custom Icons Trong Block Editor
Đây là phần mình thích nhất. Khi đăng ký icon collection qua init, icon tự động xuất hiện trong Icon block picker của editor. Mỗi collection có tab riêng, cộng với tab “All” hiển thị tất cả.
Không cần thêm code JavaScript hay register script nào. Block editor tự đọc danh sách icon qua REST API nội bộ và hiển thị trong picker. Người dùng chỉ cần kéo Icon block vào bài, chọn tab collection của bạn, pick icon.
Ngoài ra, Icon block trong 7.1 có thêm ba tính năng mới:
- Flip va rotate: Toolbar có nút flip ngang/dọc và rotate 90 do mỗi lần click.
- Default icon: Khi them Icon block moi, mac dinh hien
core/infothay vi trang. - Server-side render: Block render SVG qua
wp_get_icon(), dong nhat voi PHP frontend.
BUOC 5: Truy Xuat Icons Qua REST API
SVG Icons API cung cấp REST API endpoint để liệt kê và lấy icon. Điều này hữu ích khi build headless WordPress hoặc app riêng:
# Lay danh sach tat ca icon collections
curl -s https://yoursite.com/wp-json/wp/v2/icon-collections | jq .
# Lay danh sach icon trong collection "my-plugin"
curl -s https://yoursite.com/wp-json/wp/v2/icon-collections/my-plugin/icons | jq .
# Lay SVG cua mot icon cu the
curl -s https://yoursite.com/wp-json/wp/v2/icons/my-plugin/star | jq .Response trả về JSON gồm: tên icon, label, collection, và SVG content. Endpoint này public mặc định, không cần authentication để đọc.
Use Case Thuc Te: Them Brand Icons Cho Plugin E-commerce
Mình hay gặp case: plugin WooCommerce muốn thêm icon payment methods (Visa, Mastercard, PayPal) vào block editor để user dễ chèn vào trang thanh toán. Trước 7.1, phải dùng <img> tag hoặc inline SVG trong HTML block — lộn xộn và không nhất quán.
Với SVG Icons API, quy trình gọn hơn nhiều:
function shop_register_payment_icons() {
wp_register_icon_collection(
'shop-payments',
array(
'label' => __( 'Payment Icons', 'shop' ),
'description' => __( 'Icon cho cac phuong thuc thanh toan.', 'shop' ),
)
);
$icons = array(
'visa' => 'icons/visa.svg',
'mastercard' => 'icons/mastercard.svg',
'paypal' => 'icons/paypal.svg',
'momo' => 'icons/momo.svg',
'zalopay' => 'icons/zalopay.svg',
);
foreach ( $icons as $name => $file ) {
wp_register_icon(
"shop-payments/{$name}",
array(
'label' => ucfirst( $name ),
'file_path' => plugin_dir_path( __FILE__ ) . 'assets/' . $file,
)
);
}
}
add_action( 'init', 'shop_register_payment_icons' );Sau đoạn code này, user mở block editor, kéo Icon block vào, chọn tab “Payment Icons”, và thấy toàn bộ icon thanh toán. Không cần custom block, không cần JavaScript.
Cach Debug Khi Icon Khong Hien
Nếu đăng ký icon nhưng không thấy hiển thị, đây là checklist mình dùng:
1. Kiem tra collection da dang ky truoc icon: wp_register_icon() yêu cầu collection phải tồn tại. Nếu đăng ký icon trước collection, nó sẽ fail âm thầm.
// DUNG: collection truoc, icon sau
wp_register_icon_collection( 'my-plugin', array( 'label' => '...' ) );
wp_register_icon( 'my-plugin/star', array( 'label' => '...' ) );
// SAI: icon truoc collection
wp_register_icon( 'my-plugin/star', array( 'label' => '...' ) );
wp_register_icon_collection( 'my-plugin', array( 'label' => '...' ) );2. Kiem tra ten icon dung format: Phải có dạng collection/icon-name. Nếu chỉ truyền star mà không có namespace, đăng ký sẽ fail.
3. Kiem tra SVG khong bi sanitize het: Nếu SVG của bạn dùng element ngoài svg, path, polygon, nội dung sẽ bị strip. Kiểm tra bằng cách dump content:
$icon = wp_get_icon( 'my-plugin/star' );
error_log( $icon ); // Xem trong debug.log4. Kiem tra file_path ton tai: Vì file được đọc lazy, lỗi path không xuất hiện lúc đăng ký. Test thủ công:
$path = plugin_dir_path( __FILE__ ) . 'icons/heart.svg';
if ( ! file_exists( $path ) ) {
error_log( "File khong ton tai: $path" );
}5. Kiem tra hook priority: Nếu plugin khác gỡ collection của bạn ở priority cao hơn, icon sẽ biến mất. Đảm bảo đăng ký ở priority phù hợp:
add_action( 'init', 'my_plugin_register_icons', 10 );San Chuan Bi Cho WordPress 7.1
WordPress 7.1 chinh thuc phat hanh ngay 19/8/2026. Neu ban la developer quan ly plugin hoac theme, day la luc bat dau test. SVG Icons API se thay doi cach plugin tuong tac voi block editor — truoc can custom JavaScript, gio chi can PHP.
Mình dang nghien cuu them cac dev notes khac cua 7.1, se chia se tung phan trong cac bai toi. Neu ban co cau hoi ve SVG Icons API, comment ben duoi nhe.
Xem them: WordPress 7.1 Beta 3: Co Gi Moi Va Huong Dan Test va WordPress 7.1 Interactive Styling: Huong Dan Styling Khong Can CSS.
