# Managing Plugin Assets and Referencing Icons in OpenAI Plugins: A Complete Guide
> Learn how to manage plugin assets and reference icons in OpenAI plugins. This guide covers asset storage and manifest referencing for a complete integration.
- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-27
---
**OpenAI plugins store visual assets in a dedicated `assets/` directory and reference them via relative paths in the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest using the `icon`, `appIcon`, and `logo` fields.**
The `openai/plugins` repository standardizes how static resources are bundled and served across all plugin implementations. Understanding the relationship between the manifest configuration and the filesystem structure ensures your plugin renders correctly in the OpenAI marketplace and internal UI components.
## How Assets Are Organized in OpenAI Plugins
Each plugin in the repository follows a consistent directory structure where visual assets live in a top-level `assets/` folder. The manifest file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) uses relative paths to map these files to specific UI elements.
### Directory Structure Convention
All paths in the manifest resolve relative to the plugin root directory. For example, in the `mem` plugin, the structure appears as:
```
plugins/mem/
├── .codex-plugin/
│ └── plugin.json
└── assets/
├── icon.png
├── app-icon.png
└── logo.png
```
### Manifest Asset Fields
The plugin manifest supports three primary asset keys:
- **`icon`**: The square marketplace icon displayed next to the plugin name (typically 32×32 or 64×64 pixels)
- **`appIcon`**: The favicon-style badge used inside the plugin's UI interface
- **`logo`**: The full-size branding image shown on detail pages
## Configuring the Plugin Manifest
The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file must explicitly declare asset locations. In [`plugins/mem/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/mem/.codex-plugin/plugin.json), the configuration specifies:
```json
{
"name": "mem",
"title": "Mem",
"description": "AI-powered memory for agents.",
"icon": "assets/icon.png",
"appIcon": "assets/app-icon.png",
"logo": "assets/logo.png"
}
```
The runtime resolves these relative paths automatically and serves files through the plugin's static assets endpoint. This allows UI components to reference the same images without host-side path manipulation.
## Supported Asset Formats and Optimization
OpenAI plugins support raster and vector formats, each suited for different use cases:
- **PNG**: Use for general raster icons requiring transparency. Keep files under 50KB to prevent marketplace loading delays.
- **SVG**: Preferred for `appIcon` and `logo` fields. Vector graphics scale cleanly on high-DPI displays and maintain small file sizes.
- **ICO**: Rarely needed; only include if targeting legacy browser compatibility requirements.
When updating visual assets, always increment the manifest `version` field to invalidate cached images across the platform.
## Accessing Assets in Plugin Code
When building UI components, import assets directly to ensure path consistency with the manifest:
```tsx
import IconUrl from "./assets/icon.png";
function PluginHeader() {
return (
My Plugin
);
}
```
The build pipeline copies the entire `assets/` directory into the final artifact, preserving the relative structure defined in the manifest.
## Real-World Examples from the Repository
### Mem Plugin (PNG Implementation)
The `mem` plugin uses PNG assets for all visual elements:
- **Manifest**: [`plugins/mem/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/mem/.codex-plugin/plugin.json)
- **Icon**: `plugins/mem/assets/icon.png`
- **App Icon**: `plugins/mem/assets/app-icon.png`
### Figma Plugin (SVG Implementation)
The `figma` plugin demonstrates vector-based asset management:
- **Manifest**: [`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.codex-plugin/plugin.json)
- **Icon**: `plugins/figma/assets/icon.svg`
- **Logo**: `plugins/figma/assets/figma.svg`
### ZoomInfo Plugin (Mixed Formats)
The `zoominfo` plugin combines SVG and PNG assets:
- **Manifest**: [`plugins/zoominfo/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoominfo/.codex-plugin/plugin.json)
- **App Icon**: `plugins/zoominfo/assets/app-icon.svg`
These implementations confirm that the manifest loader accepts both formats interchangeably when referenced correctly.
## Summary
- Store all visual assets in the `assets/` directory at the plugin root level
- Reference files using relative paths in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) via `icon`, `appIcon`, and `logo` fields
- Use **SVG** for scalable icons and **PNG** for raster graphics requiring complex transparency
- Update the manifest `version` field when changing assets to clear platform caches
- Import assets directly in code to maintain path synchronization with the manifest configuration
## Frequently Asked Questions
### What directory should I use for plugin assets in OpenAI plugins?
Place all static assets in a top-level `assets/` directory within your plugin folder. The manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) references these files using relative paths like `assets/icon.png`. The build system automatically bundles this directory into the final plugin artifact.
### Can I use SVG files for OpenAI plugin icons?
Yes. The manifest supports SVG files for the `icon`, `appIcon`, and `logo` fields. The `figma` plugin demonstrates this in `plugins/figma/assets/icon.svg`. Vector graphics provide better scaling on high-resolution displays and typically produce smaller file sizes than PNG equivalents.
### How do I update an existing plugin icon in the OpenAI plugins repository?
Replace the file in `plugins//assets/` and increment the `version` field in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). Commit both changes simultaneously to ensure the platform recognizes the new asset. The version bump invalidates cached images across the marketplace and plugin UI.
### What is the difference between icon and appIcon in the plugin manifest?
The `icon` field specifies the marketplace listing image displayed alongside the plugin name in search results. The `appIcon` field defines the smaller badge used inside the plugin's own interface, such as navigation bars or headers. The `mem` plugin uses both fields in [`plugins/mem/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/mem/.codex-plugin/plugin.json) to distinguish between marketplace presentation and in-app branding.