> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks

## useActivePageKeyFromUrl

Hook returning the active dashboard page key from the URL, if any. Defaults to the first page specified in the dashboard state.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useActivePageKeyFromUrl();
```

<b>Returns:</b>

string | undefined

## useActivity

React hook returning:

* the value for the given activity key

* a function to update this value

* whether the activity is loading

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useActivity(key);
```

| Argument | Type | Description |
| :------- | :--- | :---------- |
| key      | T    |             |

<b>Returns:</b>

\[[Activity](types#activity)\[T] | null, (value: [Activity](types#activity)\[T]) => void, \{ isLoading: boolean; }]

## useAtotiClient

React hook returning the [AtotiClient](types#atoticlient) at `serverKey`.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useAtotiClient(serverKey);
```

| Argument  | Type                | Description |
| :-------- | :------------------ | :---------- |
| serverKey | string \| undefined |             |

<b>Returns:</b>

[AtotiClient](types#atoticlient) | undefined

<b>Throws:</b>

[ClientsNotFoundError](errors#clientsnotfounderror) when no clients are provided via [ClientsProvider](context-providers#clientsprovider).

[AtotiClientNotFoundError](errors#atoticlientnotfounderror) when `serverKey` is defined but no [AtotiClient](types#atoticlient) is provided for this key via [ClientsProvider](context-providers#clientsprovider).

## useAtotiClients

React hook returning the map of all registered [AtotiClient](types#atoticlient)s.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useAtotiClients();
```

<b>Returns:</b>

\{ \[serverKey: string]: [AtotiClient](types#atoticlient); }

## useConnectionStatuses

React hook returning the overall status of the connection with the registered Atoti clients.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useConnectionStatuses();
```

<b>Returns:</b>

\{ \[serverKey: string]: [ConnectionStatus](types#connectionstatus); }

## useContentClient

React hook returning the [ContentClient](types#contentclient).

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useContentClient(options);
```

| Argument | Type                                        | Description |
| :------- | :------------------------------------------ | :---------- |
| options  | \{<br />   throwIfMissing: boolean; <br />} |             |

<b>Returns:</b>

[ContentClient](types#contentclient)\<Settings> | undefined

<b>Throws:</b>

[ClientsNotFoundError](errors#clientsnotfounderror) when no clients are provided via [ClientsProvider](context-providers#clientsprovider), unless `throwIfMissing` is set to false.

[ContentClientNotFoundError](errors#contentclientnotfounderror) when no [ContentClient](types#contentclient) is provided via [ClientsProvider](context-providers#clientsprovider), unless `throwIfMissing` is set to false.

## useCube

React hook returning the cube targeted by the given `widgetState`, along with its data model and server key. Defaults `serverKey` to the key of the first provided server, when `widgetState.serverKey` is not defined. Defaults `cube` to the first cube of the target server, when `widgetState.query.mdx` does not include a cube name and no `widgetState.initialCubeName` is defined. When `throwIfMissing` is set to false, returns `undefined` instead of throwing while the target server or cube is not available yet, e.g. while its data model is still loading.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useCube(widgetState, options);
```

| Argument    | Type                                        | Description |
| :---------- | :------------------------------------------ | :---------- |
| widgetState | T \| undefined                              |             |
| options     | \{<br />   throwIfMissing: boolean; <br />} |             |

<b>Returns:</b>

TargetCube | undefined

<b>Throws:</b>

* [DataModelNotFoundError](errors#datamodelnotfounderror) if the data model is not loaded yet, unless `throwIfMissing` is set to false. - [CubeNotFoundError](errors#cubenotfounderror) if the data model does not contain any cube with the specified name, unless `throwIfMissing` is set to false. - [EmptyDataModelError](errors#emptydatamodelerror) if the data model was loaded but does not contain any cube.

## useDataModel

React hook returning the [DataModel](types#datamodel) of the Atoti server identified by `serverKey`.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useDataModel(serverKey);
```

| Argument  | Type                | Description |
| :-------- | :------------------ | :---------- |
| serverKey | string \| undefined |             |

<b>Returns:</b>

[DataModel](types#datamodel) | undefined

<b>Throws:</b>

[DataModelNotFoundError](errors#datamodelnotfounderror) when `serverKey` is defined but the data model could not be found.

## useDataModels

React hook returning the data models of all Atoti servers to which the client is connected. When `includeLoadingAndErroredDataModels` is true, also includes unreachable servers as errored.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useDataModels(options);
```

If "options.includeLoadingAndErroredDataModels" is set to false, only the successfully loaded data models will be returned.

| Argument | Type                                                         | Description |
| :------- | :----------------------------------------------------------- | :---------- |
| options  | \{<br />   includeLoadingAndErroredDataModels: true; <br />} |             |

<b>Returns:</b>

DataModels\<true>

## useIsModalMounted

Hook returning whether a modal should be mounted/unmounted depending on whether it is visible. It allows to reset the state of a Modal declaratively, without losing Ant Design's close animation.

See [https://github.com/activeviam/atoti-ui/pull/1465\\#issuecomment-862306468](https://github.com/activeviam/atoti-ui/pull/1465\\#issuecomment-862306468).

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useIsModalMounted(isModalVisible);
```

| Argument       | Type    | Description |
| :------------- | :------ | :---------- |
| isModalVisible | boolean |             |

<b>Returns:</b>

boolean

<b>For example:</b>

```
const ModalParent = () => {
  const [isModalVisible, setIsModalVisible] = useState(false);
  const isModalMounted = useIsModalMounted(isModalVisible);
  const handleModalClosed = () => {setIsModalVisible(false);};
  return isModalMounted &&
     <Modal
         isVisible={isModalVisible}
         onSubmit={handleModalClosed}
         onCancel={handleModalClosed}
      >
         <ModalChildren />
     </Modal>
}
```

## useIsPresenting

React hook returning the current state of isPresenting.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useIsPresenting();
```

<b>Returns:</b>

boolean

## useJwt

React hook returning the JWT allowing to authenticate the communication with the servers.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useJwt();
```

<b>Returns:</b>

string

## useLogout

React hook returning a callback to logout the user.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useLogout();
```

<b>Returns:</b>

(() => Promise\<void>) | null

## useMenuItemCreateFolder

React hook returning a menu item to create a folder.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useMenuItemCreateFolder(props);
```

| Argument | Type                                                 | Description |
| :------- | :--------------------------------------------------- | :---------- |
| props    | [FileListMenuItemProps](types#filelistmenuitemprops) |             |

<b>Returns:</b>

MenuItemType | null

## useMenuItemDeleteFilesAndFolders

React hook returning a menu item to delete several files and folders.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useMenuItemDeleteFilesAndFolders(props);
```

| Argument | Type                                                 | Description |
| :------- | :--------------------------------------------------- | :---------- |
| props    | [FileListMenuItemProps](types#filelistmenuitemprops) |             |

<b>Returns:</b>

MenuItemType | null

## useMenuItemExportFilesAndFolders

React hook returning a menu item to export the content of a file, a folder or a combination of files and folders.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useMenuItemExportFilesAndFolders(props);
```

| Argument | Type                                                 | Description |
| :------- | :--------------------------------------------------- | :---------- |
| props    | [FileListMenuItemProps](types#filelistmenuitemprops) |             |

<b>Returns:</b>

MenuItemType | null

## useMenuItemImportFilesAndFolders

React hook returning a menu item to import a file, a folder, or a combination of files and folders into another folder.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useMenuItemImportFilesAndFolders(props);
```

| Argument | Type                                                 | Description |
| :------- | :--------------------------------------------------- | :---------- |
| props    | [FileListMenuItemProps](types#filelistmenuitemprops) |             |

<b>Returns:</b>

MenuItemType | null

## useMenuItemMakeCopyOfFile

React hook returning a menu item to make a copy of a file.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useMenuItemMakeCopyOfFile(props);
```

| Argument | Type                                                 | Description |
| :------- | :--------------------------------------------------- | :---------- |
| props    | [FileListMenuItemProps](types#filelistmenuitemprops) |             |

<b>Returns:</b>

MenuItemType | null

## useMenuItemMoveFilesAndFolders

React hook returning a menu item to move files and folders into a folder.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useMenuItemMoveFilesAndFolders({
  onAfterSubmit,
  selectedFilesAndFolders: selectedFilesAndFoldersOrServer,
  pathToParentFolder,
  contentTree,
  contentType,
});
```

| Argument                                                                                                                                                                  | Type                                                 | Description |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- | :---------- |
| \{<br />   onAfterSubmit,<br />   selectedFilesAndFolders: selectedFilesAndFoldersOrServer,<br />   pathToParentFolder,<br />   contentTree,<br />   contentType, <br />} | [FileListMenuItemProps](types#filelistmenuitemprops) |             |

<b>Returns:</b>

MenuItemType | null

## useMenuItemRenameFileOrFolder

React hook returning a menu item to rename a folder or a file.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useMenuItemRenameFileOrFolder(props);
```

| Argument | Type                                                 | Description |
| :------- | :--------------------------------------------------- | :---------- |
| props    | [FileListMenuItemProps](types#filelistmenuitemprops) |             |

<b>Returns:</b>

MenuItemType | null

## useMenuItemShareFileOrFolder

React hook returning a menu item to edit permissions for the underlying file or folder.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useMenuItemShareFileOrFolder({
  selectedFilesAndFolders,
  pathToParentFolder,
  contentType,
});
```

| Argument                                                                                     | Type                                                 | Description |
| :------------------------------------------------------------------------------------------- | :--------------------------------------------------- | :---------- |
| \{<br />   selectedFilesAndFolders,<br />   pathToParentFolder,<br />   contentType, <br />} | [FileListMenuItemProps](types#filelistmenuitemprops) |             |

<b>Returns:</b>

MenuItemType | null

## useModal

React hook returning functions to open a modal, and close the active modal. The functions are provided by a [ModalsProvider](context-providers#modalsprovider).

Note: in most cases, you do <strong>not</strong> need this API, and you can use a regular declarative [\<Modal />](https://ant.design/components/modal). This imperative API is useful when the modal lifecycle needs to be decoupled from that of its trigger, for example when opening a modal through a context menu item.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useModal();
```

<b>Returns:</b>

\{ openModal: \{ \<PropsType extends object>(modalKey: string, initialProps: PropsType): void; (modalKey: string): void; }; closeModal: () => void; }

## useOnDataModelClicked

React hook accepting a listener on data model tree clicks. Calls this listener each time a node is clicked in the data model tree.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useOnDataModelClicked(listener);
```

| Argument | Type                                                   | Description |
| :------- | :----------------------------------------------------- | :---------- |
| listener | [DataModelClickListener](types#datamodelclicklistener) |             |

<b>Returns:</b>

void

## useOnDataModelNodeClickedForDataVisualizationWidget

React hook allowing to add fields onto a data visualization widget. To be used on a [WidgetPlugin](types#widgetplugin).

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useOnDataModelNodeClickedForDataVisualizationWidget(widgetState);
```

| Argument    | Type        | Description |
| :---------- | :---------- | :---------- |
| widgetState | WidgetState |             |

<b>Returns:</b>

(node: [DataModelNode](types#datamodelnode)) => WidgetState

## usePermission

React hook returning:

* the permission value for the given key

* a function to update this permission when authenticated as a user with admin privileges

* an object indicating whether the permissions are loading and whether the permission has explicitly been set

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
usePermission(key);
```

| Argument | Type | Description |
| :------- | :--- | :---------- |
| key      | T    |             |

<b>Returns:</b>

\[ [Permissions](types#permissions)\[T], (value: [Permissions](types#permissions)\[T]) => Promise\<void>, \{ isLoading: boolean; isSet: boolean; } ]

## usePersisted

React hook returning the value for the `key` in the browser local storage and the function to update it.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
usePersisted(key, initialValue);
```

| Argument     | Type   | Description |
| :----------- | :----- | :---------- |
| key          | string |             |
| initialValue | T      |             |

<b>Returns:</b>

\[T | undefined, (newValue: T) => void]

## usePositionInDashboard

Returns the [PositionInDashboard](types#positionindashboard) of the widget in the dashboard.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
usePositionInDashboard();
```

<b>Returns:</b>

[PositionInDashboard](types#positionindashboard) | null

## useQuery

React hook returning the up-to-date [Query](types#query) corresponding to `queryId`.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useQuery({
  serverKey,
  queryId,
});
```

| Argument                                       | Type                                                             | Description |
| :--------------------------------------------- | :--------------------------------------------------------------- | :---------- |
| \{<br />   serverKey,<br />   queryId, <br />} | \{<br />   serverKey?: string;<br />   queryId?: string; <br />} |             |

<b>Returns:</b>

[Query](types#query)\<[MdxString](types#mdxstring)> | undefined

## useQueryResult

React hook allowing to subscribe to a query's result. If `query` is provided, also runs the query.

`serverKey` identifies which server to run the query against. `queryId` identifies the query. `query` is the MDX that indicates which data to retrieve from Atoti Server. This data is displayed in the widget.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useQueryResult({
  serverKey,
  queryId,
  query,
});
```

| Argument                                                      | Type                                                                                                                                  | Description |
| :------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ | :---------- |
| \{<br />   serverKey,<br />   queryId,<br />   query, <br />} | \{<br />   serverKey?: string;<br />   queryId?: string;<br />   query?: [Query](types#query)\<[MdxString](types#mdxstring)>; <br />} |             |

<b>Returns:</b>

[QueryResult](types#queryresult)\<ResultType>

<b>Remarks:</b>

If `queryId` is not provided, the subscription is canceled and an empty result is returned.

## useRequestInit

Returns the requestInit from the React context.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useRequestInit();
```

<b>Returns:</b>

RequestInit

## useSetting

React hook returning:

* the setting value for the given key

* a function to update this setting

* an object containing a property for whether the settings are loading

See [CoreSettings](types#coresettings)

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useSetting(key);
```

| Argument | Type | Description |
| :------- | :--- | :---------- |
| key      | K    |             |

<b>Returns:</b>

\[ Settings\[K], (newValue: Settings\[K]) => Promise\<void>, \{ isLoading: boolean; } ]

## useSwitchedWidgetState

React Hook returning the switched widget state if switched or the original state if not switched.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useSwitchedWidgetState(widgetState, queryId);
```

| Argument    | Type        | Description |
| :---------- | :---------- | :---------- |
| widgetState | WidgetState |             |
| queryId     | string      |             |

<b>Returns:</b>

WidgetState

## useTheme

React hook returning the [Theme](types#theme).

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useTheme();
```

<b>Returns:</b>

[Theme](types#theme)

## useTree

React hook returning the dashboards or widgets tree.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useTree(type, options);
```

| Argument | Type                                                     | Description |
| :------- | :------------------------------------------------------- | :---------- |
| type     | T                                                        |             |
| options  | \{<br />   throwIfContentClientMissing: boolean; <br />} |             |

<b>Returns:</b>

[ContentRecord](types#contentrecord)\<[DashboardMetaData](types#dashboardmetadata) | [WidgetMetaData](types#widgetmetadata) | [FilterMetaData](types#filtermetadata)> | null

<b>Throws:</b>

[ContentClientNotFoundError](errors#contentclientnotfounderror) when no [ContentClient](types#contentclient) is provided via [ClientsProvider](context-providers#clientsprovider), unless `throwIfContentClientMissing` is set to false.

## useUser

React hook returning the [User](types#user).

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useUser(options);
```

| Argument | Type                                        | Description |
| :------- | :------------------------------------------ | :---------- |
| options  | \{<br />   throwIfMissing: boolean; <br />} |             |

<b>Returns:</b>

[User](types#user) | undefined

<b>Throws:</b>

[UserNotFoundError](errors#usernotfounderror) when no [User](types#user) is provided via [UserProvider](context-providers#userprovider), unless `throwIfMissing` is set to false.

## useUserNames

React hook returning the provided usernames from context.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useUserNames();
```

<b>Returns:</b>

[UserName](types#username)\[] | null

## useUserRoles

React hook returning the user roles from context.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useUserRoles();
```

<b>Returns:</b>

[UserRole](types#userrole)\[] | null

## useWebsocketHeaders

React hook returning the headers to be set on "REGISTER" and "UPDATE" websocket messages.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useWebsocketHeaders();
```

<b>Returns:</b>

Record\<string, string> | undefined

## useWidgetName

React Hook returning either widgetState.name if defined otherwise returns a translated initial name from the widget plugin.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useWidgetName(widgetState);
```

| Argument    | Type                               | Description |
| :---------- | :--------------------------------- | :---------- |
| widgetState | [AWidgetState](types#awidgetstate) |             |

<b>Returns:</b>

string

## useWidgetPluginKeys

React hook returning the keys of all the registered widget plugins.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useWidgetPluginKeys();
```

<b>Returns:</b>

string\[]

## useWidgetPlugins

React hook returning the widget plugins corresponding to `widgetKeys`.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useWidgetPlugins(widgetKeys);
```

| Argument   | Type      | Description |
| :--------- | :-------- | :---------- |
| widgetKeys | string\[] |             |

<b>Returns:</b>

[WidgetPlugin](types#widgetplugin)\[]

## useWidgetQueryResult

React hook running the widget's [Query](types#query), impacted by the user/dashboard/page filters and query contexts, and returning its result. When the widget is in an inactive dashboard page or deferred updates are enabled: - The query is paused if it was in real-time mode. - Updates to the query on the client side are not forwarded to the server.

```typescript theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
useWidgetQueryResult({
  serverKey,
  queryId,
  widgetState,
  dashboardState,
  pageKey,
  cube,
  queryRanges,
  isDeferred,
});
```

| Argument                                                                                                                                                            | Type                                                                                                                                                                                                                                                                                                                                                                                                                                        | Description |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- |
| \{<br />   serverKey,<br />   queryId,<br />   widgetState,<br />   dashboardState,<br />   pageKey,<br />   cube,<br />   queryRanges,<br />   isDeferred, <br />} | \{<br />   serverKey?: string;<br />   queryId?: string;<br />   widgetState: [WidgetWithQueryState](types#widgetwithquerystate)\<MdxType>;<br />   dashboardState?: [DashboardState](types#dashboardstate);<br />   pageKey?: string;<br />   cube: [Cube](types#cube);<br />   queryRanges?: Partial\<\{<br />     \[axisId in [AxisId](types#axisid)]: [QueryRange](types#queryrange); <br />  }>;<br />   isDeferred?: boolean; <br />} |             |

<b>Returns:</b>

[QueryResult](types#queryresult)\<MdxType extends [MdxSelect](types#mdxselect) ? [CellSet](types#cellset) : [DrillthroughResult](types#drillthroughresult)>