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.

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

1. Install in your Jellyfin project:

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

2. Basic integration (add to your index.html):

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

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

For more detailed installation instructions, see the Installation section.

🔹 Main Script Repository
📁 jf-avatars

🔹 Image Collection Repository
🖼️ jf-avatars-images

• 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.

The application currently supports the following languages:

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

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).

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

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

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'

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.

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

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/

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.

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

1. Direct Injection in index.html:

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

2. 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
   }

• 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.

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

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

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.

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.

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

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.

To add a new language, create a JSON file in the appropriate format and place it in the translations directory. Consult existing files as templates.

Yes! You can use your own avatars by setting the CSS property --jf-avatars-url-images to point to your image metadata JSON file.

While designed for Jellyfin, the script can be adapted to other web applications by modifying the selectors and events in the source code.

Check that all paths are correct and file permissions are appropriate. Also ensure that Jellyfin has been restarted after installation.

Contributions to this project are welcome! Here's how you can contribute:

1. Fork the repository
2. Create a branch for your feature (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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.

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

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