DOCSEARCHbyAlgolia
Submit Docs

Material Symbols for Home Assistant

repository·main·Indexed 42 days ago

https://github.com/beecho01/material-symbols

Integration providing access to over 16,000 Google Material Symbols within the Home Assistant ecosystem. Supports six distinct styles—Outlined (m3o), Outlined and filled (m3of), Rounded (m3r), Rounded and filled (m3rf), Sharp (m3s), and Sharp and filled (m3sf)—usable in the Lovelace UI via specific prefixes.

Tokens
3.5K
Snippets
10
Records
20
Agent score
52%

What's inside Material Symbols

  1. How the Material Symbols auto-update system works

    main

    The automation system ensures the repository stays synchronized with the iconify Material Symbols repository through a scheduled or manual workflow.

    1. Triggering

    • Daily Schedule: Automatically runs every day at 2 AM UTC.
    • Manual Trigger: Can be initiated via the GitHub Actions UI.

    2. Detection Logic

    The system compares the latest commit hash of json/material-symbols.json from the Iconify repository against a locally stored hash in .github/iconify-hash.txt.

    • If the hashes match: No action is taken.
    • If the hashes differ: An update is triggered.

    3. Update Lifecycle

    When an update is triggered, the system:

    1. Generates Icons: Downloads the latest JSON and generates SVGs for all 6 variants.
    2. Manages Versions: Updates material_symbols.js and manifest.json using a YYYY.MM.DD format.
    3. Updates Documentation: Refreshes the README with the new icon count.
    4. Commits Changes: Automatically performs a git add, git commit, and git push with a descriptive message (e.g., 🤖 Auto-update Material Symbols icons (v2025.08.23)).

  2. Regenerate all Material Symbols icons and assets

    main

    To perform a full regeneration of the icon set, including downloading the latest icons from Iconify, generating all SVG files for the 6 style variants, creating icons.json files, updating the README icon count, and bumping the JavaScript and manifest versions, run the generate_svgs.py script.

    This is the primary command for manual updates and ensures all assets (approximately 15,556 icons) are synchronized with the latest source.

    cd custom_components/material_symbols/data
python generate_svgs.py

  3. Monitor and trigger GitHub Actions automation

    main

    The automation is managed via GitHub Actions. You can monitor the status of the "Auto-update Material Symbols Icons" workflow in the Actions tab of your repository.

    To manually trigger the icon count update:

    1. Navigate to the Actions tab.
    2. Select the Update Icon Count in README workflow.
    3. Click Run workflow.

  4. Use Material Symbols in Home Assistant Lovelace UI

    main

    Once installed, you can use Material Symbols by specifying an icon using the format prefix:icon_name in your entity configuration or YAML.

    To find the exact string for an icon, use the Icon Finder Tool. Clicking an icon will copy the Home Assistant compatible entry (e.g., m3o:light) to your clipboard.

    icon: 'prefix:icon_name'

  5. Verify automation results

    main

    Use the following methods to ensure the automation has run correctly:

    Check Git History

    Look for automated commits with the prefix 🤖. Example command:

    git log --oneline -n 5

    Compare README changes

    Check the icon count string in README.md before and after running the automation:

    grep "collection of" README.md

    Check Workflow Logs

    In GitHub Actions, inspect the logs for these specific status messages:

    • ✓ Updated README.md with icon count: X,XXX
    • ℹ No changes needed in README.md
    # Look for commits like "🤖 Auto-update icon count in README"
git log --oneline -n 5

# Before making changes, note the current count
grep "collection of" README.md

# After running automation, check if it changed
grep "collection of" README.md

  6. Test Material Symbols automation locally

    main

    You can run the automation pipeline locally to process icons and test update detection before pushing changes.

    To perform complete icon processing (which includes icon counting, README updates, and version management), navigate to the data directory and run generate_svgs.py. To specifically test if the system correctly detects updates, run test_update_detection.py from the root.

    # Complete icon processing (includes count, README update, version management)
cd custom_components/material_symbols/data
python generate_svgs.py

# Test update detection
python scripts/test_update_detection.py

  7. Migrate from v1.X.X to 202X.X.X

    main

    When upgrading from version 1.X.X to the 202X.X.X series, it is recommended to fully uninstall the existing repository and remove all traces of it from your system to prevent conflicts. The migration process depends on how you originally installed the icons.

    If installed via HACS:

    1. Search for Material Symbols in HACS and select the repository.
    2. Open the repository menu (3 vertical dots) and select Remove.
    3. Confirm the removal in the pop-up.
    4. In your Home Assistant dashboard, go to Resources via the menu icon (3 vertical dots).
    5. Remove any JavaScript module ending in material-symbols.js.
    6. Restart Home Assistant.
    7. Clear your browser's cache.
    8. Follow the new Installation steps.

    If installed via configuration.yaml:

    1. Remove the material-symbols.js entry from your frontend configuration:
      frontend:
  extra_module_url:
    - /local/community/material-symbols/material-symbols.js
      (or wherever you placed the file).
    2. Delete the physical files from their location on your system.
    3. Restart Home Assistant.
    4. Clear your browser's cache.
    5. Follow the new Installation steps.

    If installed via Dashboard UI Resources:

    1. Go to your dashboard's Resources section via the menu icon (3 vertical dots).
    2. Remove any JavaScript module ending in material-symbols.js.
    3. Delete the physical files from their location on your system.
    4. Restart Home Assistant.
    5. Clear your browser's cache.
    6. Follow the new Installation steps.
    frontend:
  extra_module_url:
    - /local/community/material-symbols/material-symbols.js

  8. Install Material Symbols via HACS (Recommended)

    main

    The easiest way to install Material Symbols is through the Home Assistant Community Store (HACS) as a Default Integration.

    1. Use the HACS repository quick-link to add the repository to your Home Assistant instance.
    2. Use the setup quick-link to start the configuration flow.
    3. Restart Home Assistant to load the integration.

    Note: You may need to clear your browser cache to see the icons correctly after installation.

    https://my.home-assistant.io/redirect/hacs_repository/?owner=beecho01&repository=material-symbols

  9. Install Material Symbols manually

    main

    If you are not using HACS, follow these steps to install the integration manually:

    1. Download the Integration: Download the material_symbols folder from the custom_components directory of the repository.
    2. Copy to Home Assistant: Place the folder into your Home Assistant config/custom_components/ directory. The path must be config/custom_components/material_symbols/.
    3. Restart Home Assistant: Restart to load the new files.
    4. Add Integration:
      • Go to Settings → Devices & Services.
      • Click + Add Integration.
      • Search for Material Symbols and select it.
      • Click Finish.
    5. Restart Home Assistant: Perform a final restart to complete the setup.

  11. Debug console errors in the browser

    main

    To investigate icon loading issues or performance problems, use the browser developer tools:

    1. Open developer tools (press F12).
    2. Navigate to the Console tab.
    3. Filter or look for messages prefixed with Material Symbols:.

    Key Log Messages to Watch For:

    • Material Symbols: Starting initialisation: The integration is beginning its startup process.
    • Material Symbols: Integration ready: The integration has successfully initialized.
    • Material Symbols: Fetched X/6 icon lists successfully: Indicates the progress of icon list loading.
    • Material Symbols: Custom icons defined for all sets: Indicates the setup is complete.

  12. Fix icons not loading after page refresh

    main

    If icons appear correctly while editing a dashboard but disappear after a refresh or behave inconsistently, try the following steps:

    User Workarounds:

    • Hard Refresh: Perform a complete browser cache clear (e.g., Ctrl+Shift+R) or hard refresh multiple times.
    • Dashboard Navigation: Navigate to a different dashboard and back to trigger a resource reload.
    • Force Refresh: Enter and exit dashboard edit mode.
    • Restart: Restart Home Assistant if the issue persists.

    Developer Note: Versions 2025.08.23 and later include integration readiness checking, retry mechanisms for failed requests, and improved cache invalidation to mitigate these race conditions.