jf-avatars

October 24, 2025 · View on GitHub

GitHub release (latest by date)

Description

jf-avatars is a JavaScript library that allows users to select avatars from an image gallery in a Jellyfin compatible environment. The application provides a user-friendly interface via a custom modal, facilitating the selection of profile images from an organized collection.

🚀 Getting Started

To quickly get started with jf-avatars, follow these steps:

Install in your Jellyfin project:

git clone https://github.com/kalibrado/jf-avatars.git

Basic integration (add to your index.html):

<script type="module" src="jf-avatars/src/js/index.js"></script>

Test the functionality by accessing the user profile editing page in Jellyfin.

For more detailed installation instructions, see the Installation section.

📦 Repositories

🔹 Main Script Repository
📁 jf-avatars

🔹 Image Collection Repository
🖼️ jf-avatars-images

✨ Features

Avatar Selection: Intuitive interface for browsing and choosing avatars from an image gallery.
Responsive Image Grid: Displays images in a grid format, adapted to all screen sizes.
Search and Filter: Image search functionality by name and filtering by category through a dropdown menu.
Visual State Management: Selected images are displayed in color while unselected ones appear in grayscale.
Internationalization: Automatic language detection without needing CSS. The application dynamically loads the correct language based on the user's preferences.
Integration with Jellyfin: Seamlessly integrates with Jellyfin themes, providing a cohesive experience.

🌐 Available Languages

The application currently supports the following languages:

Flag	Language	Code
🇬🇧	English	`en`
🇪🇸	Spanish	`es`
🇫🇷	French	`fr`
🇮🇹	Italian	`it`
🇵🇹	Portuguese	`pt`
🇹🇷	Turkish	`tr`

🖼️ Screenshots

Here are some screenshots demonstrating the functionality and UI of the jf-avatars project across different devices.

Desktop View

Desktop Full Modal View Desktop Modal Open (Selected) Desktop Modal Open (Closed)

Mobile View

Mobile Modal Open (Closed) Mobile Modal Open (Selected) Mobile Full Modal View

🧩 Project Structure

The project is structured as follows:

index.js: Entry point for initializing the application and injecting the modal.
events.js: Event handlers for user interactions (searching, filtering).
props.js: Dynamic properties and application state (selected image).
style.js: Functions to adjust the modal's style based on screen size.
ui-elements.js: Generation of user interface elements (buttons, dropdown, image grid).

🔧 Installation

🧩 Integration with Jellyfin (Docker and non-Docker setups)

This project can be integrated into Jellyfin in both Docker-based and native installations.

🐳 Docker Setup

1. Clone the repository

git clone https://github.com/kalibrado/jf-avatars.git

2. Mount the volume in your Jellyfin container

In your docker-compose.yml file, add the following volume to the Jellyfin service:

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    volumes:
      - '/path/to/jf-avatars:/jellyfin/jellyfin-web/jf-avatars'
      - '/path/to/index.html:/jellyfin/jellyfin-web/index.html:ro'

3. Edit `index.html`

In your custom index.html (mounted as read-only), add the following line before </body>:

<script type="module" src="jf-avatars/src/js/index.js"></script>

⚠️ Make sure you edit this file before launching the container, as it's mounted read-only.

💻 Native Installation (Non-Docker)

1. Clone the repository

git clone https://github.com/kalibrado/jf-avatars.git

2. Copy the folder into Jellyfin's web directory

The default web directory varies depending on your system:

Linux: /usr/share/jellyfin/web or /usr/lib/jellyfin/web
Windows: C:\Program Files\Jellyfin\Server\jellyfin-web

Copy the folder:

sudo cp -r jf-avatars /usr/share/jellyfin/web/

3. Edit `index.html`

Open index.html in the root of the web/ folder and add:

<script type="module" src="jf-avatars/src/js/index.js"></script>

📌 It is recommended to place the line just before </body> for clean integration.

Once Jellyfin is restarted, the custom avatar selector will load as part of the Jellyfin web interface.

Plugin Installation

1. Install the Custom JavaScript Plugin

2. Navigate to Jellyfin dashboard -> plugins -> custom javascript plugin

3. Paste contents of the latest release's `main.js` into the textbox

4. Save and restart Jellyfin

🌐 Remote Integration

You can integrate the script into your project without direct file copying using these methods:

Direct Injection in index.html:

<script
  type="module"
  src="https://github.com/kalibrado/jf-avatars/releases/download/{version}/main.js"
  defer
></script>

Injection via Nginx:

location / {
    proxy_pass http://backend_server;  # Reverse proxy to your backend
    sub_filter '</body>' '<script type="module" src="https://github.com/kalibrado/jf-avatars/releases/download/{version}/main.js" defer></script></body>';
    sub_filter_once on;  # Apply the modification only once
}

General Functioning

Loading the Avatar Selection Modal: Detects the #btnDeleteImage button and adds a new button to open the modal.
Image Selection: Click on an image to select it. Selected images appear in color, while unselected ones are in grayscale.
Image Search: Use the search bar to locate specific images by name.
Category Filtering: Select a category from the dropdown to filter images.

Advanced Usage Examples

Customizing the image source

// Set a custom URL for avatar images
document.documentElement.style.setProperty('--jf-avatars-url-images', 'https://my-server.com/my-avatars/images_metadata.json');

Integration with custom events

// Listen for avatar selection event
document.addEventListener('jf-avatars-selected', function(event) {
  console.log('Avatar selected:', event.detail.imageUrl);
  // Perform additional actions...
});

Image Management

The default images come from the repository jf-avatars-images. This repository maintains an organized collection of avatars.

If users wish to use their own images, they can specify a custom image URL using the CSS property:

--jf-avatars-url-images: "https://your-custom-url.com/path/to/images_metadata.json";

To ensure proper functionality, images should follow the naming convention defined in the images_metadata.json file.

Language Management

The language management is fully automatic and does not require any manual configuration. The correct language is dynamically loaded based on the user's browser preferences.

The application attempts to load the appropriate language file (e.g., fr.json, en.json) from the local server, and if not found, falls back to a GitHub repository.

Integration with the Jellyfin Theme

All elements created by the script are designed to integrate seamlessly with Jellyfin's theme, ensuring a smooth user experience, even with custom themes.

📚 Documentation with JSDoc

The project is fully documented using JSDoc. To generate the documentation from the source code, run the following command:

npm run docs

This will create comprehensive documentation in a docs directory.

Fork the repository
Create a branch for your feature (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please read the CONTRIBUTING.md file for more details on our code of conduct and the process for submitting Pull Requests.

🙏 Acknowledgments

Special thanks to BobHasNoSoul for the inspiration and for sharing the images used in this project.

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

3. Paste contents of the latest release's main.js into the textbox

3. Paste contents of the latest release's `main.js` into the textbox