> For the complete documentation index, see [llms.txt](https://docs.navigaglobal.com/dashboard-plugin/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.navigaglobal.com/dashboard-plugin/api-and-gui/api/register/portals.md).

# Portals

## What is a Portal and what can I do with it?

A portal is a component that a plugin exports in order to be used internally or by other plugins.

To be able to register Portals with Dashboard you should pass an Array of objects with key \`portals\` and each object of your Portals should contain a valid React component and a uniq id to be target the Portal with that id.

#### Portal object:

```javascript
{
    id: 'my-awesome-portal',
    name: 'My awesome portal',
    description: 'A portal component will render an image within a stylish frame',
    component: MyPortalComponent
}
```

#### example

> Registering a portal with Dashboard.

```javascript
import DashboardPlugin from 'Dashboard/plugin'

const Plugin = new DashboardPlugin('@plugin_bundle')

const registerPlugin = () => {
    const { Application } = require('@components/Application')
    const { MyAwesomePortal } = require('@components/MyAwesomePortal')
    
    Plugin.register({
        application: Application,

        portals: [
            {
                id: 'my-awesome-portal',
                name: 'My awesome portal',
                description: 'A portal component will render an image within a stylish frame',
                component: MyAwesomePortal
            }
        ]
    })
}

registerPlugin()

export {
    Plugin
}
```

Now your Portal has been register in Dashboard with the given id 'my-awesome-portal' and can be used with other plugin.

{% hint style="info" %}
A portal component can only be a valid react component.
{% endhint %}

#### example

{% tabs %}
{% tab title="Function based" %}

```jsx
import { forwardRef } from 'react'

import {
    Wrapper,
    StyledImg
} from './style'

const PortalComponent = (props, ref) => {
    const { imageSrc, onImageLoaded } = props

    return (
        <Wrapper ref={ref}>
            <StyledImg
                src={imageSrc}
                onLoad={onImageLoaded}
            />
        </Wrapper>
    )
}

const MyAwesomePortal = forwardRef(PortalComponent)

export {
    MyAwesomePortal
}
```

{% endtab %}
{% endtabs %}

Now after we have our portal component, we can import it and use it in our plugin and other plugins can also use it and render it

## How to use a Portal?

You can use a portal in your plugin with the method \`getPortal\` that can be accessible from the Plugin-API

And by passing the Portal id to \`getPortal\` it will return the portal component and ready to use in your plugin.

#### example

> We will use the Portal that we just registered with the other plugin 👆🏽 with the giving id 'my-awesome-portal'

{% content-ref url="/pages/-MCg1j4U8w042h4MrXb3" %}
[getPortal](/dashboard-plugin/api-and-gui/api/getportal.md)
{% endcontent-ref %}

####

#### Results:

![ImagePortal](/files/-LeB4pm0BdsSLjkdut3J)

### 💁‍♀️Tips for writing Portals&#x20;

* **Don't connect your portal with your application redux state if you are using one**

  when connecting a portal component with redux state it won't get the state from redux HOC, because your portal component won't be rendered within the `redux provider` for your state, it's rendered outside the provider context, you can of course have an internal state for your portal and connect all the children with portal's state
* **Don't wrap your portal with any of your application contextHOCs if there is any**

  Same like the redux connect, your portal component will be rendered outside of your `context provider`
* **Style**

  all the style rules will work fine in your portal, but if you are using `styled-components` and you have a custom theme and you wrap your application with a `theme provider`the same applies here. in this case you should wrap your portal with another theme provider and pass the theme object as a prop.
* **Config**

  your portal component will get your plugin config by default such like `Application, Widget ..` from props


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.navigaglobal.com/dashboard-plugin/api-and-gui/api/register/portals.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.