Template Tags API Reference

This page provides complete API documentation for Django RemixIcon template tags.

Template tags for rendering RemixIcons in Django templates.

django_remix_icon.templatetags.remix_icon_tags.get_all_icon_names()[source]: Get a flat list of all icon names with ‘ri-’ prefix.

django_remix_icon.templatetags.remix_icon_tags.remix_icon(icon_name, **kwargs)[source]

Render a RemixIcon with optional attributes.

Usage:: {% remix_icon ‘ri-home-line’ %} {% remix_icon ‘ri-user-fill’ class=’text-blue-500’ size=’24’ %} {% remix_icon instance.icon_field %} {% remix_icon ‘ri-heart-line’ style=’color: red; font-size: 20px;’ %}

Parameters:

icon_name – The RemixIcon name (e.g., ‘ri-home-line’)
**kwargs – Additional HTML attributes (class, style, size, etc.)

Returns:

HTML <i> tag with the icon

django_remix_icon.templatetags.remix_icon_tags.remix_icon_css()[source]

Include RemixIcon CSS from CDN.

Usage:: {% remix_icon_css %}

Returns:: HTML link tag for RemixIcon CSS

django_remix_icon.templatetags.remix_icon_tags.remix_icon_version()[source]

Get the RemixIcon version being used.

Usage:: {% remix_icon_version %}

Returns:: Version string

django_remix_icon.templatetags.remix_icon_tags.is_remix_icon(icon_name)[source]

Check if a string is a valid RemixIcon name.

Usage:

{% if icon_field|is_remix_icon %}: {% remix_icon icon_field %}

{% endif %}

Parameters:: icon_name – The icon name to check
Returns:: Boolean indicating if the icon name is valid

django_remix_icon.templatetags.remix_icon_tags.remix_icon_with_text(icon_name, text, **kwargs)[source]

Render an icon with accompanying text.

Usage:: {% remix_icon_with_text ‘ri-home-line’ ‘Home’ %} {% remix_icon_with_text instance.icon ‘Click here’ class=’btn btn-primary’ %}

Parameters:

icon_name – The RemixIcon name
text – Text to display alongside the icon
**kwargs – Additional HTML attributes for the container

Returns:

Rendered template with icon and text

django_remix_icon.templatetags.remix_icon_tags.remix_icon_list(category=None, limit=None)[source]

Get a list of RemixIcon names, optionally filtered by category.

Usage:: {% remix_icon_list as all_icons %} {% remix_icon_list category=’Arrows’ limit=10 as arrow_icons %} {% remix_icon_list category=’user’ limit=10 as user_icons %}

Parameters:

category – Filter icons by category name or search in icon names (optional)
limit – Limit number of icons returned (optional)

Returns:

List of icon names (with ‘ri-’ prefix)

Loading Template Tags

Before using any template tag, load the tags in your template:

{% load remix_icon_tags %}

Template Tags

remix_icon

django_remix_icon.templatetags.remix_icon_tags.remix_icon(icon_name, **kwargs)[source]

Render a RemixIcon with optional attributes.

Usage:: {% remix_icon ‘ri-home-line’ %} {% remix_icon ‘ri-user-fill’ class=’text-blue-500’ size=’24’ %} {% remix_icon instance.icon_field %} {% remix_icon ‘ri-heart-line’ style=’color: red; font-size: 20px;’ %}

Parameters:

icon_name – The RemixIcon name (e.g., ‘ri-home-line’)
**kwargs – Additional HTML attributes (class, style, size, etc.)

Returns:

HTML <i> tag with the icon

Function Signature:

def remix_icon(icon_name, **kwargs):
    """
    Render a RemixIcon with optional attributes.

    Args:
        icon_name (str): The RemixIcon name (e.g., 'ri-home-line')
        **kwargs: Additional HTML attributes

    Returns:
        SafeString: HTML <i> tag with the icon
    """

Parameters:

icon_name (str): Required. The RemixIcon class name (e.g., ‘ri-home-line’)
**kwargs: Optional HTML attributes for the <i> element

Special Attributes:

class (str): Additional CSS classes (combined with icon class)
size (str|int): Font size (converted to CSS font-size property)
style (str): Inline CSS styles

Returns:

SafeString containing an HTML <i> element.

Examples:

<!-- Basic usage -->
{% remix_icon 'ri-home-line' %}
<!-- Output: <i class="ri-home-line"></i> -->

<!-- With CSS class -->
{% remix_icon 'ri-heart-fill' class='text-red-500' %}
<!-- Output: <i class="ri-heart-fill text-red-500"></i> -->

<!-- With size -->
{% remix_icon 'ri-star-line' size='24' %}
<!-- Output: <i class="ri-star-line" style="font-size: 24px;"></i> -->

<!-- With multiple attributes -->
{% remix_icon 'ri-settings-line' class='icon-btn' title='Settings' data-action='open-settings' %}
<!-- Output: <i class="ri-settings-line icon-btn" title="Settings" data-action="open-settings"></i> -->

Error Handling:

If an invalid icon name is provided:

{% remix_icon 'invalid-icon' %}
<!-- Output: <i class="ri-question-line" title="Invalid icon: invalid-icon"></i> -->

remix_icon_css

django_remix_icon.templatetags.remix_icon_tags.remix_icon_css()[source]

Include RemixIcon CSS from CDN.

Usage:: {% remix_icon_css %}

Returns:: HTML link tag for RemixIcon CSS

Function Signature:

def remix_icon_css():
    """
    Include RemixIcon CSS from CDN.

    Returns:
        SafeString: HTML link tag for RemixIcon CSS
    """

Parameters:

None.

Returns:

SafeString containing an HTML <link> element.

Usage:

{% remix_icon_css %}
<!-- Output: <link href="https://cdn.jsdelivr.net/npm/remixicon@4.7.0/fonts/remixicon.css" rel="stylesheet"> -->

Best Practices:

Include this tag once in your base template’s <head> section:

<!DOCTYPE html>
<html>
<head>
    <title>My Site</title>
    {% load remix_icon_tags %}
    {% remix_icon_css %}
</head>
<body>
    <!-- Your content -->
</body>
</html>

remix_icon_version

django_remix_icon.templatetags.remix_icon_tags.remix_icon_version()[source]

Get the RemixIcon version being used.

Usage:: {% remix_icon_version %}

Returns:: Version string

Function Signature:

def remix_icon_version():
    """
    Get the RemixIcon version being used.

    Returns:
        str: Version string
    """

Parameters:

None.

Returns:

str containing the RemixIcon version number.

Usage:

<p>RemixIcon version: {% remix_icon_version %}</p>
<!-- Output: RemixIcon version: 4.7.0 -->

remix_icon_with_text

django_remix_icon.templatetags.remix_icon_tags.remix_icon_with_text(icon_name, text, **kwargs)[source]

Render an icon with accompanying text.

Usage:: {% remix_icon_with_text ‘ri-home-line’ ‘Home’ %} {% remix_icon_with_text instance.icon ‘Click here’ class=’btn btn-primary’ %}

Parameters:

icon_name – The RemixIcon name
text – Text to display alongside the icon
**kwargs – Additional HTML attributes for the container

Returns:

Rendered template with icon and text

Function Signature:

def remix_icon_with_text(icon_name, text, **kwargs):
    """
    Render an icon with accompanying text.

    Args:
        icon_name (str): The RemixIcon name
        text (str): Text to display alongside the icon
        **kwargs: Additional HTML attributes for the container

    Returns:
        dict: Template context for rendering
    """

Parameters:

icon_name (str): Required. The RemixIcon class name
text (str): Required. Text to display with the icon
**kwargs: Optional HTML attributes for the container element

Returns:

Rendered template context using django_remix_icon/icon_with_text.html.

Usage:

{% remix_icon_with_text 'ri-home-line' 'Home' %}
{% remix_icon_with_text menu_item.icon menu_item.name class='nav-item' %}

Template Context:

The inclusion tag provides these context variables:

icon_name: The icon name
text: The text to display
attrs: Dictionary of HTML attributes
is_valid_icon: Boolean indicating if the icon is valid

Default Template:

<!-- django_remix_icon/icon_with_text.html -->
{% load remix_icon_tags %}
<span{% for key, value in attrs.items %} {{ key }}="{{ value }}"{% endfor %}>
    {% if is_valid_icon %}
        {% remix_icon icon_name %}
    {% else %}
        <i class="ri-question-line" title="Invalid icon: {{ icon_name }}"></i>
    {% endif %}
    {% if text %}
        <span class="icon-text">{{ text }}</span>
    {% endif %}
</span>

remix_icon_list

django_remix_icon.templatetags.remix_icon_tags.remix_icon_list(category=None, limit=None)[source]

Get a list of RemixIcon names, optionally filtered by category.

Usage:: {% remix_icon_list as all_icons %} {% remix_icon_list category=’Arrows’ limit=10 as arrow_icons %} {% remix_icon_list category=’user’ limit=10 as user_icons %}

Parameters:

category – Filter icons by category name or search in icon names (optional)
limit – Limit number of icons returned (optional)

Returns:

List of icon names (with ‘ri-’ prefix)

Function Signature:

def remix_icon_list(category=None, limit=None):
    """
    Get a list of RemixIcon names, optionally filtered by category.

    Args:
        category (str, optional): Filter icons by category
        limit (int, optional): Limit number of icons returned

    Returns:
        list: List of icon names
    """

Parameters:

category (str, optional): Filter icons containing this string
limit (int, optional): Maximum number of icons to return

Returns:

list of icon name strings.

Usage:

<!-- Get all icons -->
{% remix_icon_list as all_icons %}

<!-- Get user-related icons -->
{% remix_icon_list category='user' as user_icons %}

<!-- Get limited icons -->
{% remix_icon_list limit=20 as featured_icons %}

<!-- Combine filters -->
{% remix_icon_list category='home' limit=5 as home_icons %}

Examples:

<!-- Icon picker -->
{% remix_icon_list category='user' limit=10 as user_icons %}
<div class="icon-picker">
    {% for icon in user_icons %}
        <button data-icon="{{ icon }}">
            {% remix_icon icon %}
            <small>{{ icon }}</small>
        </button>
    {% endfor %}
</div>

<!-- Icon count -->
{% remix_icon_list as all_icons %}
<p>{{ all_icons|length }} icons available</p>

Template Filters

is_remix_icon

django_remix_icon.templatetags.remix_icon_tags.is_remix_icon(icon_name)[source]

Check if a string is a valid RemixIcon name.

Usage:

{% if icon_field|is_remix_icon %}: {% remix_icon icon_field %}

{% endif %}

Parameters:: icon_name – The icon name to check
Returns:: Boolean indicating if the icon name is valid

Function Signature:

def is_remix_icon(icon_name):
    """
    Check if a string is a valid RemixIcon name.

    Args:
        icon_name (str): The icon name to check

    Returns:
        bool: True if valid RemixIcon name, False otherwise
    """

Parameters:

icon_name (str): The string to validate

Returns:

bool indicating if the icon name is valid.

Usage:

{% if menu_item.icon|is_remix_icon %}
    {% remix_icon menu_item.icon %}
    {{ menu_item.name }}
{% else %}
    <span class="no-icon">{{ menu_item.name }}</span>
{% endif %}

Examples:

<!-- Conditional rendering -->
{% for item in items %}
    <li class="menu-item">
        {% if item.icon|is_remix_icon %}
            {% remix_icon item.icon class='menu-icon' %}
        {% endif %}
        <span>{{ item.name }}</span>
    </li>
{% endfor %}

<!-- With default fallback -->
{% for post in posts %}
    <article>
        <h2>
            {% if post.category.icon|is_remix_icon %}
                {% remix_icon post.category.icon %}
            {% else %}
                {% remix_icon 'ri-article-line' %}
            {% endif %}
            {{ post.title }}
        </h2>
    </article>
{% endfor %}

Usage Patterns

Basic Icon Rendering

<!-- Simple icon -->
{% remix_icon 'ri-home-line' %}

<!-- Icon with model field -->
{% remix_icon user.profile.icon %}

<!-- Icon with size -->
{% remix_icon 'ri-star-fill' size='20' %}

Icon Buttons

<button type="button" class="btn btn-primary">
    {% remix_icon 'ri-save-line' size='16' %}
    Save Changes
</button>

Status Indicators

<div class="status-indicator">
    {% if task.completed %}
        {% remix_icon 'ri-check-circle-fill' class='text-success' %}
    {% elif task.in_progress %}
        {% remix_icon 'ri-loader-line' class='text-info spinning' %}
    {% else %}
        {% remix_icon 'ri-circle-line' class='text-muted' %}
    {% endif %}
    {{ task.status_text }}
</div>

Icon Grids

<div class="icon-grid">
    {% remix_icon_list category='business' limit=12 as business_icons %}
    {% for icon in business_icons %}
        <div class="icon-item">
            {% remix_icon icon size='32' %}
            <small>{{ icon|slice:"3:" }}</small>
        </div>
    {% endfor %}
</div>

Form Buttons

<form method="post">
    {% csrf_token %}
    {{ form }}
    <div class="form-actions">
        <button type="submit" name="action" value="save">
            {% remix_icon 'ri-save-line' %} Save
        </button>
        <button type="submit" name="action" value="save_continue">
            {% remix_icon 'ri-save-2-line' %} Save & Continue
        </button>
        <a href="{% url 'cancel' %}" class="btn btn-secondary">
            {% remix_icon 'ri-close-line' %} Cancel
        </a>
    </div>
</form>

Advanced Examples

Dynamic Icon Selection

<!-- JavaScript-powered icon selector -->
<div class="dynamic-icon-selector">
    <input type="hidden" name="selected_icon" id="icon-input">
    <div class="current-selection">
        <span id="selected-icon">
            {% remix_icon 'ri-image-line' %}
        </span>
        <span id="selected-name">ri-image-line</span>
    </div>

    <div class="icon-categories">
        {% for category in icon_categories %}
            <div class="category" data-category="{{ category }}">
                <h4>{{ category|title }}</h4>
                {% remix_icon_list category=category limit=20 as category_icons %}
                <div class="icons">
                    {% for icon in category_icons %}
                        <button type="button" class="icon-option" data-icon="{{ icon }}">
                            {% remix_icon icon %}
                        </button>
                    {% endfor %}
                </div>
            </div>
        {% endfor %}
    </div>
</div>

<script>
document.querySelectorAll('.icon-option').forEach(button => {
    button.addEventListener('click', function() {
        const iconName = this.dataset.icon;
        document.getElementById('icon-input').value = iconName;
        document.getElementById('selected-icon').innerHTML = `<i class="${iconName}"></i>`;
        document.getElementById('selected-name').textContent = iconName;
    });
});
</script>

Conditional Icon Display

{% for notification in notifications %}
    <div class="notification notification-{{ notification.type }}">
        {% if notification.type == 'success' %}
            {% remix_icon 'ri-check-circle-line' class='text-success' %}
        {% elif notification.type == 'warning' %}
            {% remix_icon 'ri-alert-line' class='text-warning' %}
        {% elif notification.type == 'error' %}
            {% remix_icon 'ri-error-warning-line' class='text-danger' %}
        {% else %}
            {% remix_icon 'ri-information-line' class='text-info' %}
        {% endif %}

        <div class="notification-content">
            <h5>{{ notification.title }}</h5>
            <p>{{ notification.message }}</p>
        </div>
    </div>
{% endfor %}

Icon with Loading States

<button type="submit" class="btn btn-primary" id="save-btn">
    <span class="btn-icon">
        {% remix_icon 'ri-save-line' %}
    </span>
    <span class="btn-text">Save</span>
</button>

<script>
document.getElementById('save-btn').addEventListener('click', function() {
    // Show loading state
    this.querySelector('.btn-icon').innerHTML = '<i class="ri-loader-line spinning"></i>';
    this.querySelector('.btn-text').textContent = 'Saving...';
    this.disabled = true;
});
</script>

Performance Considerations

Template Caching

For better performance with large icon lists:

{% load cache %}
{% cache 3600 icon_grid %}
    {% remix_icon_list as all_icons %}
    <div class="icon-grid">
        {% for icon in all_icons %}
            {% remix_icon icon %}
        {% endfor %}
    </div>
{% endcache %}

Lazy Loading

For pages with many icons:

<div class="icon-container" data-icons='[{% for icon in icons %}"{{ icon }}"{% if not forloop.last %},{% endif %}{% endfor %}]'>
    <!-- Icons loaded via JavaScript -->
</div>

<script>
// Load icons progressively
const container = document.querySelector('.icon-container');
const icons = JSON.parse(container.dataset.icons);

icons.forEach((icon, index) => {
    setTimeout(() => {
        const iconEl = document.createElement('i');
        iconEl.className = icon;
        container.appendChild(iconEl);
    }, index * 10);
});
</script>

Error Handling

The template tags handle various error conditions gracefully:

Invalid Icon Names:

{% remix_icon 'invalid-icon' %}
<!-- Renders: <i class="ri-question-line" title="Invalid icon: invalid-icon"></i> -->

Empty Values:

{% remix_icon '' %}
<!-- Renders: (empty string) -->

{% remix_icon None %}
<!-- Renders: (empty string) -->

Missing Variables:

{% remix_icon undefined_variable %}
<!-- Django template error or empty string depending on settings -->

Best Practices

Always load RemixIcon CSS:

{% load remix_icon_tags %}
{% remix_icon_css %}

Use conditional rendering for optional icons:

{% if item.icon|is_remix_icon %}
    {% remix_icon item.icon %}
{% endif %}

Provide fallback icons:

{% remix_icon item.icon|default:'ri-circle-line' %}

Use semantic HTML with icons:

<button type="submit">
    {% remix_icon 'ri-save-line' %}
    <span class="sr-only">Save</span>
</button>

Cache icon lists for better performance:

{% load cache %}
{% cache 3600 navigation_icons %}
    <!-- Navigation with icons -->
{% endcache %}

Template Tags API Reference

Loading Template Tags

Template Tags

remix_icon

remix_icon_css

remix_icon_version

remix_icon_with_text

remix_icon_list

Template Filters

is_remix_icon

Usage Patterns

Basic Icon Rendering

Icon Buttons

Navigation Menus

Status Indicators

Icon Grids

Form Buttons

Advanced Examples

Dynamic Icon Selection

Conditional Icon Display

Icon with Loading States

Performance Considerations

Template Caching

Lazy Loading

Error Handling

Best Practices