NUI Resource Access

How to access images and other assets from other resources in your NUI/HTML interfaces.

---

Cross-Resource Asset URLs

FiveM provides special URL schemes to access assets from other resources:

CFX-NUI Scheme

<!-- Basic format -->
https://cfx-nui-<resourcename>/<path>/<file>

<!-- Example: Access inventory weapon image -->
https://cfx-nui-qb-inventory/html/images/weapon_pistol.png

NUI Scheme

<!-- Alternative format -->
nui://<resourcename>/<path>/<file>

<!-- Example: Access icon from another resource -->
nui://resourcename/client/html/assets/icons/icon.png

---

Usage Examples

In HTML/CSS

<!-- Image tag -->
<img src="https://cfx-nui-cv_inventory/html/images/weapon_pistol.png" alt="Pistol">

<!-- Background image -->
<div style="background-image: url('https://cfx-nui-cv_hud/html/assets/logo.png')"></div>

In CSS Files

.weapon-icon {
    background-image: url('https://cfx-nui-cv_inventory/html/images/weapon_pistol.png');
    width: 64px;
    height: 64px;
}

.character-avatar {
    background: url('nui://cv_character/client/html/assets/default-avatar.jpg');
}

In JavaScript/React

// Direct image source
const imageSrc = `https://cfx-nui-${resourceName}/html/images/${itemName}.png`;

// React component
<img 
    src={`https://cfx-nui-cv_inventory/html/images/${item.image}`} 
    alt={item.label}
/>

// Dynamic resource access
const getItemImage = (item) => {
    return `nui://${item.resource}/html/images/${item.icon}.png`;
};

---

Important Notes

Resource Files Must Be Declared

Assets must be declared in the source resource's fxmanifest.lua:

ui_page 'html/index.html'

files {
    'html/index.html',
    'html/images/*.png',
    'html/css/*.css',
    'html/js/*.js'
}

Path Considerations

• Paths are relative to the resource root, not the html folder
• Use forward slashes / in paths
• File names are case-sensitive on Linux servers
• Special characters in filenames should be URL-encoded

Security

• Only files declared in files {} are accessible
• NUI assets are accessible to all resources (no permission system)
• Don't store sensitive data in NUI-accessible files

---

Common Use Cases

Shared Item Icons

Access inventory item images from multiple resources:

// In your NUI code
const inventoryResource = 'cv_inventory';
const itemIcon = `https://cfx-nui-${inventoryResource}/html/images/${itemName}.png`;

Fallback Images

Provide fallback for missing images:

const handleImageError = (e) => {
    e.target.src = 'https://cfx-nui-cv_core/html/images/default.png';
};

<img 
    src={`https://cfx-nui-cv_inventory/html/images/${item}.png`}
    onError={handleImageError}
    alt="Item"
/>

Loading External Resource Assets

-- In your Lua code, send resource name to NUI
SendNUIMessage({
    action = "loadImage",
    resource = "cv_inventory",
    path = "html/images/weapon_pistol.png"
})

// In your NUI JavaScript
window.addEventListener('message', (event) => {
    if (event.data.action === 'loadImage') {
        const imageUrl = `https://cfx-nui-${event.data.resource}/${event.data.path}`;
        document.getElementById('item-image').src = imageUrl;
    }
});

---

Troubleshooting

Image not loading: - Verify the file exists in the source resource - Check that the file is listed in files {} in fxmanifest.lua - Ensure the resource is started and loaded - Check browser console (F8 → enable NUI DevTools) for 404 errors

Wrong path: - Remember paths are from resource root, not html/ folder - If file is at cv_inventory/html/images/icon.png: - ✅ Correct: https://cfx-nui-cv_inventory/html/images/icon.png - ❌ Wrong: https://cfx-nui-cv_inventory/images/icon.png

Case sensitivity: - Linux servers are case-sensitive - weapon_Pistol.png ≠ weapon_pistol.png - Use consistent lowercase naming for cross-platform compatibility

---

Best Practices

1. Centralize Assets: Keep shared images in a common resource (e.g., cv_assets)
2. Use Constants: Define resource names as constants to avoid typos
3. Cache Busting: Not supported - restart resource if assets change
4. Optimize Images: Compress images to reduce load times
5. Consistent Naming: Use a clear naming convention for assets
6. Document Dependencies: Note which external resources your NUI depends on