faicons

library0.2.2pypypi✓ verified 87d ago

faicons is a Python library that provides an interface to Font-Awesome for use in Shiny for Python applications. It enables developers to easily embed scalable vector graphic (SVG) icons from Font Awesome 6.2.0 into their Shiny UI. The current version is 0.2.2, with releases occurring infrequently, typically for minor improvements or Font Awesome version updates.

web-framework

pip install faicons

github ↗package ↗

INSTALL

IMPORT

SIG · FAICONS

faicons

web-frameworkpythonv0.2.2

Install

1.8s avg

Import

291ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.305s · 23MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.8s · import 0.277s · 23MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

icon_svg

✓ from faicons import icon_svg

This example demonstrates how to integrate `faicons.icon_svg` into a basic Shiny for Python application to add Font Awesome icons to UI elements like action buttons.

from shiny import App, ui from faicons import icon_svg app_ui = ui.page_fluid( ui.h2("Shiny App with faicons"), ui.input_action_button("like_button", "Like", icon=icon_svg("thumbs-up")), ui.input_action_button("share_button", "Share", icon=icon_svg("share-alt")), ui.output_text("feedback"), ) def server(input, output, session): @ui.reactive.Effect @ui.event(input.like_button) def _(): ui.notification_show("You liked it!") @ui.reactive.Effect @ui.event(input.share_button) def _(): ui.notification_show("You shared it!") app = App(app_ui, server)

Debug

Known issues

gotchaThe library is currently listed with a '2 - Pre-Alpha' development status on PyPI, indicating it is still in early development and APIs might be subject to change.

fix

Be aware that the API may not be fully stable. Review release notes for any breaking changes in future versions.

affects: 0.2.2 and earlier

gotchaThe `icon_svg()` function's `height` and `width` parameters expect a numerical value followed by a CSS length unit (e.g., '100px', '2em'), not a percentage value like '100%'. Providing a percentage will raise a `ValueError`.

fix

Use explicit CSS length units (e.g., `icon_svg("icon-name", height="2em")`) or manage sizing via parent CSS rules.

affects: 0.2.2 and earlier

gotchafaicons currently uses Font Awesome 6.2.0. Font Awesome 7.0 introduced significant breaking changes (e.g., fixed-width icons by default, changes to SVG path classes, removal of legacy webfonts). Icons and styling expectations from FA7 might not apply or work as expected with faicons.

fix

Refer to the Font Awesome 6.2.0 documentation for available icons and their exact names. Be aware that newer FA7 features or icons might not be present or compatible. Consider external CSS for FA7 compatibility if needed.

affects: 0.2.2 and earlier

gotchaWhile faicons provides a Python interface for Font Awesome icons, it is specifically designed 'for use in Shiny for Python'. Directly generating standalone SVG strings with `icon_svg()` outside of a framework that renders HTML (like Shiny) may require additional handling to display them correctly in a web context.

fix

Ensure `faicons` is used within a compatible web framework like Shiny for proper rendering. If used independently, embed the output of `icon_svg()` into HTML content that supports SVG rendering.

affects: All versions

Errors

Common errors & fixes

ValueError: Values provided to `height` and `width` must have a numerical value followed by a CSS length unit.

The `height` or `width` parameter in `faicons.icon_svg()` was provided with a percentage value (e.g., '100%'), which is not directly supported; it expects a numerical value followed by a valid CSS length unit (e.g., '1em', '24px') or just a number for pixels.

fix

Provide a numerical value with an explicit CSS unit like 'px', 'em', 'rem', or simply a number for pixel values (e.g., `icon_svg('gear', height='24px')` or `icon_svg('gear', height=24)`).

The `name` provided ('<icon-name>') does not correspond to a known icon

The icon name used in `faicons.icon_svg()` is either misspelled, does not exist in Font Awesome 6.2.0 (the version `faicons` uses), or is a Font Awesome Pro icon being requested without a Pro setup. This often happens when using older Font Awesome 4 names (e.g., 'map-o' instead of 'map').

fix

Consult the Font Awesome 6.2.0 documentation for the correct icon name and ensure you are using a free icon if you do not have a Font Awesome Pro license. For example, change `icon_svg('map-o')` to `icon_svg('map')`.

ModuleNotFoundError: No module named 'faicons'

The `faicons` library is not installed in the current Python environment, or the environment where the code is being executed does not have access to the installed package.

fix

Install the library using pip: `pip install faicons`.

Font Awesome icons not displaying (showing as squares or blank in Shiny app)

Icons may not display correctly due to an incorrect icon name, referencing a Font Awesome Pro icon when only free icons are available, or a conflict with other CSS styles overriding Font Awesome.

fix

Verify that the icon name is correct and corresponds to a free icon available in Font Awesome 6.2.0. Check for any conflicting CSS rules in your Shiny application that might be preventing Font Awesome styles from rendering properly.

Upgrade

Version history

0.2.2latest on PyPI · released Jan 16, 2024

Audit

Dependencies

htmltoolsrequiredUsed for generating HTML elements, which icons are rendered as.

typing-extensionsrequiredProvides backported and experimental type hints.

shinyoptionalThe primary framework faicons is designed to integrate with, though not a direct installation dependency.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/rstudio/py-faicons ↗

packagehttps://pypi.org/project/faicons/ ↗