> For the complete documentation index, see [llms.txt](https://docs.kojascripts.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kojascripts.eu/free/carmarket/configuration/custom-vehicle-images.md).

# Custom Vehicle Images

By default the tablet UI fetches vehicle images from **`https://docs.fivem.net/vehicles/<respname>.webp`** — that covers every stock GTA V vehicle, but **not** modded cars on your server.

This page shows how to ship your own images for custom vehicles.

***

## How it works

1. You put an image file at `web/build/images/vehicles/<respname>.webp`.
2. You register the `respname` in `Config.CustomVehicleImages`.
3. The UI loads **listed** respnames from your local resource and **falls back** to `docs.fivem.net` for everything else.

***

## Steps

{% stepper %}
{% step %}

### Get the vehicle image

Recommended specs:

* **Format:** `.webp` (PNG works but is larger)
* **Size:** `512 × 256`
* **Background:** transparent
* **Crop:** vehicle centered, side or 3⁄4 view
  {% endstep %}

{% step %}

### Drop it in the right folder

Save it as `<respname>.webp` in:

```
koja-carmarket/web/build/images/vehicles/
```

The filename **must** match the spawn model exactly, in lowercase:

```
web/build/images/vehicles/mymodcar1.webp   ✅
web/build/images/vehicles/MyModCar1.webp   ❌ (case mismatch)
web/build/images/vehicles/mymodcar1.png    ❌ (wrong format unless you set up otherwise)
```

{% hint style="info" %}
If you're contributing to the source tree, drop it in `web/public/images/vehicles/` instead — Vite will copy it to `web/build/` during `bun run build`.
{% endhint %}
{% endstep %}

{% step %}

### Register it in the config

{% code title="shared/config.lua" %}

```lua
Config.CustomVehicleImages = {
    'mymodcar1',
    'mymodcar2',
    'supercarx',
}
```

{% endcode %}

Names are normalized to lowercase server-side, but it's good practice to write them lowercase here too.
{% endstep %}

{% step %}

### Restart and test

`restart koja-carmarket`. Open the tablet — your custom vehicle should now show with the local image instead of a missing-image placeholder.

{% hint style="warning" %}
If you only added the config entry but **not** the actual file, the tablet will silently show the missing-image fallback. Double-check the file path.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Troubleshooting

| Symptom                                   | Likely cause                                                               |
| ----------------------------------------- | -------------------------------------------------------------------------- |
| Image shows for stock cars but not modded | Respname missing from `Config.CustomVehicleImages`                         |
| Modded car shows placeholder icon         | File not in `web/build/images/vehicles/` or name mismatch (case-sensitive) |
| Everything broken after rebuild           | Did you forget to `restart koja-carmarket` after building?                 |

***

## Bulk-registering many vehicles

If you have a vehicle pack with dozens of cars, just list them all:

```lua
Config.CustomVehicleImages = {
    'audi_r8', 'bmw_m4', 'mercedes_amg',
    'ferrari_488', 'lambo_huracan', 'porsche_911',
    -- ...
}
```

No artificial cap — the lookup is an `O(1)` `Set` on the frontend.