@livekit/components-js-docs 0.1.0 → 0.1.2

package/generated-docs/react/hook/useismuted_1.md

@@ -1,20 +1,31 @@
+---
+{
+  "title": "useIsMuted",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useIsMuted.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useIsMuted
 
-> Warning: This API is now obsolete.
->
-> This overload will be removed in a future version, pass in trackRef instead.
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+This overload will be removed in a future version, pass in trackRef instead.
+
+{% /callout %}
 
 ## Import
 
 ```typescript
-import { useIsMuted } from '@livekit/components-react';
+import { useIsMuted } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="source" type="Track.Source" optional=false %}
 {% /parameter %}

package/generated-docs/react/hook/useisspeaking.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useIsSpeaking",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useIsSpeaking.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useIsSpeaking
@@ -7,7 +14,7 @@ The `useIsSpeaking` hook returns a `boolean` that indicates if the participant i
 ## Import
 
 ```typescript
-import { useIsSpeaking } from '@livekit/components-react';
+import { useIsSpeaking } from "@livekit/components-react";
 ```
 
 ## Usage
@@ -18,7 +25,7 @@ const isSpeaking = useIsSpeaking(participant);
 
 {% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="participant" type="Participant" optional=true %}
 {% /parameter %}

package/generated-docs/react/hook/uselayoutcontext.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useLayoutContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/layout-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useLayoutContext
@@ -7,7 +14,7 @@ Ensures that a layout context is provided via context. If no layout context is p
 ## Import
 
 ```typescript
-import { useLayoutContext } from '@livekit/components-react';
+import { useLayoutContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/hook/uselivekitroom.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useLiveKitRoom",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useLiveKitRoom.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useLiveKitRoom
@@ -7,7 +14,7 @@ The `useLiveKitRoom` hook is used to implement the `LiveKitRoom` or your custom
 ## Import
 
 ```typescript
-import { useLiveKitRoom } from '@livekit/components-react';
+import { useLiveKitRoom } from "@livekit/components-react";
 ```
 
 ## Usage
@@ -19,9 +26,66 @@ return <div {...htmlProps}>...</div>;
 
 {% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
+
+{% parameter name="serverUrl" type="string | undefined" optional=false %}
+URL to the LiveKit server. For example: `wss://<domain>.livekit.cloud` To simplify the implementation, `undefined` is also accepted as an intermediate value, but only with a valid string url can the connection be established.
+
+{% /parameter %}
+
+{% parameter name="token" type="string | undefined" optional=false %}
+A user specific access token for a client to authenticate to the room. This token is necessary to establish a connection to the room. To simplify the implementation, `undefined` is also accepted as an intermediate value, but only with a valid string token can the connection be established.
+
+{% /parameter %}
+
+{% parameter name="audio" type="AudioCaptureOptions | boolean" optional=true %}
+Publish audio immediately after connecting to your LiveKit room.
+
+{% /parameter %}
+
+{% parameter name="connect" type="boolean" optional=true %}
+If set to true a connection to LiveKit room is initiated.
+
+{% /parameter %}
+
+{% parameter name="connectOptions" type="RoomConnectOptions" optional=true %}
+Define options how to connect to the LiveKit server.
+
+{% /parameter %}
+
+{% parameter name="onConnected" type="() => void" optional=true %}
+{% /parameter %}
+
+{% parameter name="onDisconnected" type="() => void" optional=true %}
+{% /parameter %}
+
+{% parameter name="onError" type="(error: Error) => void" optional=true %}
+{% /parameter %}
+
+{% parameter name="onMediaDeviceFailure" type="(failure?: MediaDeviceFailure) => void" optional=true %}
+{% /parameter %}
+
+{% parameter name="options" type="RoomOptions" optional=true %}
+Options for when creating a new room. When you pass your own room instance to this component, these options have no effect. Instead, set the options directly in the room instance.
+
+{% /parameter %}
+
+{% parameter name="room" type="Room" optional=true %}
+Optional room instance. By passing your own room instance you overwrite the `options` parameter, make sure to set the options directly on the room instance itself.
+
+{% /parameter %}
+
+{% parameter name="screen" type="ScreenShareCaptureOptions | boolean" optional=true %}
+Publish screen share immediately after connecting to your LiveKit room.
+
+{% /parameter %}
+
+{% parameter name="simulateParticipants" type="number | undefined" optional=true %}
+{% /parameter %}
+
+{% parameter name="video" type="VideoCaptureOptions | boolean" optional=true %}
+Publish video immediately after connecting to your LiveKit room.
 
-{% parameter name="props" type="LiveKitRoomProps" optional=false %}
 {% /parameter %}
 
 ## Returns

package/generated-docs/react/hook/uselocalparticipant.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useLocalParticipant",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useLocalParticipant.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useLocalParticipant
@@ -7,7 +14,7 @@ The `useLocalParticipant` hook returns the local participant and the associated
 ## Import
 
 ```typescript
-import { useLocalParticipant } from '@livekit/components-react';
+import { useLocalParticipant } from "@livekit/components-react";
 ```
 
 ## Usage
@@ -18,7 +25,7 @@ const { localParticipant } = useLocalParticipant();
 
 {% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="options" type="UseLocalParticipantOptions" optional=true %}
 {% /parameter %}

package/generated-docs/react/hook/uselocalparticipantpermissions.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useLocalParticipantPermissions",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useLocalParticipantPermissions.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useLocalParticipantPermissions
@@ -7,7 +14,7 @@ The `useLocalParticipantPermissions` hook returns the local participant's permis
 ## Import
 
 ```typescript
-import { useLocalParticipantPermissions } from '@livekit/components-react';
+import { useLocalParticipantPermissions } from "@livekit/components-react";
 ```
 
 ## Usage
@@ -21,5 +28,5 @@ const { canPublish, canPublishData } = useLocalParticipantPermissions();
 ## Returns
 
 ```typescript
-import('livekit-client/dist/src/proto/livekit_models_pb').ParticipantPermission | undefined;
+import("livekit-client/dist/src/proto/livekit_models_pb").ParticipantPermission | undefined;
 ```

package/generated-docs/react/hook/usemaybelayoutcontext.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useMaybeLayoutContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/layout-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMaybeLayoutContext
@@ -7,7 +14,7 @@ Returns a layout context from the `LayoutContext` if it exists, otherwise `undef
 ## Import
 
 ```typescript
-import { useMaybeLayoutContext } from '@livekit/components-react';
+import { useMaybeLayoutContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/hook/usemaybeparticipantcontext.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useMaybeParticipantContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/participant-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMaybeParticipantContext
@@ -7,7 +14,7 @@ Returns a participant from the `ParticipantContext` if it exists, otherwise `und
 ## Import
 
 ```typescript
-import { useMaybeParticipantContext } from '@livekit/components-react';
+import { useMaybeParticipantContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/hook/usemayberoomcontext.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useMaybeRoomContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/room-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMaybeRoomContext
@@ -7,7 +14,7 @@ Returns the room context if it exists, otherwise undefined.
 ## Import
 
 ```typescript
-import { useMaybeRoomContext } from '@livekit/components-react';
+import { useMaybeRoomContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/hook/usemaybetrackcontext.md

@@ -1,17 +1,28 @@
+---
+{
+  "title": "useMaybeTrackContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/track-reference-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMaybeTrackContext
 
-> Warning: This API is now obsolete.
->
-> `useMaybeTrackContext` has been to `useMaybeTrackRefContext`<!-- -->, use this as a drop in replacement.
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+`useMaybeTrackContext` has been renamed to `useMaybeTrackRefContext`<!-- -->, use this as a drop in replacement.
+
+{% /callout %}
 
 Returns a track reference from the `TrackContext` if it exists, otherwise `undefined`<!-- -->.
 
 ## Import
 
 ```typescript
-import { useMaybeTrackContext } from '@livekit/components-react';
+import { useMaybeTrackContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/hook/usemaybetrackrefcontext.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useMaybeTrackRefContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/track-reference-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMaybeTrackRefContext
@@ -7,7 +14,7 @@ Returns a track reference from the `TrackRefContext` if it exists, otherwise `un
 ## Import
 
 ```typescript
-import { useMaybeTrackRefContext } from '@livekit/components-react';
+import { useMaybeTrackRefContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/hook/usemediadevices.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useMediaDevices",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useMediaDevices.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMediaDevices
@@ -7,23 +14,23 @@ The `useMediaDevices` hook returns the list of media devices of a given kind.
 ## Import
 
 ```typescript
-import { useMediaDevices } from '@livekit/components-react';
+import { useMediaDevices } from "@livekit/components-react";
 ```
 
 ## Usage
 
 ```tsx
-const videoDevices = useMediaDevices({ kind: 'videoinput' });
-const audioDevices = useMediaDevices({ kind: 'audioinput' });
+const videoDevices = useMediaDevices({ kind: "videoinput" });
+const audioDevices = useMediaDevices({ kind: "audioinput" });
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="{ kind }" type="{
-    kind: MediaDeviceKind;
-}" optional=false %}
+      kind: MediaDeviceKind;
+  }" optional=false %}
 {% /parameter %}
 
 ## Returns

package/generated-docs/react/hook/usemediadeviceselect.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useMediaDeviceSelect",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useMediaDeviceSelect.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMediaDeviceSelect
@@ -7,22 +14,33 @@ The `useMediaDeviceSelect` hook is used to implement the `MediaDeviceSelect` com
 ## Import
 
 ```typescript
-import { useMediaDeviceSelect } from '@livekit/components-react';
+import { useMediaDeviceSelect } from "@livekit/components-react";
 ```
 
 ## Usage
 
 ```tsx
 const { devices, activeDeviceId, setActiveMediaDevice } = useMediaDeviceSelect({
-  kind: 'audioinput',
+  kind: "audioinput"
 });
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
+
+{% parameter name="kind" type="MediaDeviceKind" optional=false %}
+{% /parameter %}
+
+{% parameter name="requestPermissions" type="boolean" optional=true %}
+this will call getUserMedia if the permissions are not yet given to enumerate the devices with device labels. in some browsers multiple calls to getUserMedia result in multiple permission prompts. It's generally advised only flip this to true, once a (preview) track has been acquired successfully with the appropriate permissions.
+
+{% /parameter %}
+
+{% parameter name="room" type="Room" optional=true %}
+{% /parameter %}
 
-{% parameter name="{ kind, room, track, requestPermissions, }" type="UseMediaDeviceSelectProps" optional=false %}
+{% parameter name="track" type="LocalAudioTrack | LocalVideoTrack" optional=true %}
 {% /parameter %}
 
 ## Returns

package/generated-docs/react/hook/usemediatrack.md

@@ -1,20 +1,31 @@
+---
+{
+  "title": "useMediaTrack",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useMediaTrack.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMediaTrack
 
-> Warning: This API is now obsolete.
->
-> use `useTrack` instead
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+use `useTrack` instead
+
+{% /callout %}
 
 ## Import
 
 ```typescript
-import { useMediaTrack } from '@livekit/components-react';
+import { useMediaTrack } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="source" type="VideoSource | AudioSource" optional=false %}
 {% /parameter %}
@@ -29,10 +40,10 @@ import { useMediaTrack } from '@livekit/components-react';
 
 ```typescript
 {
-  publication: import('livekit-client').TrackPublication | undefined;
+  publication: import("livekit-client").TrackPublication | undefined;
   isMuted: boolean | undefined;
   isSubscribed: boolean | undefined;
-  track: import('livekit-client').Track | undefined;
+  track: import("livekit-client").Track | undefined;
   elementProps: React.HTMLAttributes<HTMLElement>;
 }
 ```

package/generated-docs/react/hook/usemediatrackbyname.md

@@ -1,20 +1,31 @@
+---
+{
+  "title": "useMediaTrackByName",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useMediaTrackByName.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMediaTrackByName
 
-> Warning: This API is now obsolete.
->
-> This function will be removed in a future version, use `useTrackByName` instead.
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+This function will be removed in a future version, use `useTrackByName` instead.
+
+{% /callout %}
 
 ## Import
 
 ```typescript
-import { useMediaTrackByName } from '@livekit/components-react';
+import { useMediaTrackByName } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="name" type="string" optional=false %}
 {% /parameter %}
@@ -29,10 +40,10 @@ import { useMediaTrackByName } from '@livekit/components-react';
 
 ```typescript
 {
-  publication: import('livekit-client').TrackPublication | undefined;
+  publication: import("livekit-client").TrackPublication | undefined;
   isMuted: boolean | undefined;
   isSubscribed: boolean | undefined;
-  track: import('livekit-client').Track | undefined;
-  elementProps: import('react').HTMLAttributes<HTMLElement>;
+  track: import("livekit-client").Track | undefined;
+  elementProps: import("react").HTMLAttributes<HTMLElement>;
 }
 ```

package/generated-docs/react/hook/usepagination.md

@@ -0,0 +1,52 @@
+---
+{
+  "title": "usePagination",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/usePagination.ts"
+}
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# usePagination
+
+The `usePagination` hook implements simple pagination logic for use with arrays.
+
+## Import
+
+```typescript
+import { usePagination } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const tracks = useTracks();
+const pagination = usePagination(4, tracks);
+
+<TrackLoop tracks={pagination.tracks} />;
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
+
+## Properties
+
+{% parameter name="itemPerPage" type="number" optional=false %}
+{% /parameter %}
+
+{% parameter name="trackReferences" type="TrackReferenceOrPlaceholder[]" optional=false %}
+{% /parameter %}
+
+## Returns
+
+```typescript
+{
+    totalPageCount: number;
+    nextPage: () => void;
+    prevPage: () => void;
+    setPage: (num: number) => void;
+    firstItemIndex: number;
+    lastItemIndex: number;
+    tracks: TrackReferenceOrPlaceholder[];
+    currentPage: number;
+}
+```

package/generated-docs/react/hook/useparticipantcontext.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useParticipantContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/participant-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useParticipantContext
@@ -7,7 +14,7 @@ Ensures that a participant is provided via context. If not inside a `Participant
 ## Import
 
 ```typescript
-import { useParticipantContext } from '@livekit/components-react';
+import { useParticipantContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/hook/useparticipantinfo.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useParticipantInfo",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useParticipantInfo.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useParticipantInfo
@@ -5,12 +12,12 @@
 ## Import
 
 ```typescript
-import { useParticipantInfo } from '@livekit/components-react';
+import { useParticipantInfo } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="props" type="UseParticipantInfoOptions" optional=true %}
 {% /parameter %}

package/generated-docs/react/hook/useparticipantpermissions.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useParticipantPermissions",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useParticipantPermissions.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useParticipantPermissions
@@ -5,12 +12,12 @@
 ## Import
 
 ```typescript
-import { useParticipantPermissions } from '@livekit/components-react';
+import { useParticipantPermissions } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="options" type="UseParticipantPermissionsOptions" optional=true %}
 {% /parameter %}
@@ -18,5 +25,5 @@ import { useParticipantPermissions } from '@livekit/components-react';
 ## Returns
 
 ```typescript
-import('livekit-client/dist/src/proto/livekit_models_pb').ParticipantPermission | undefined;
+import("livekit-client/dist/src/proto/livekit_models_pb").ParticipantPermission | undefined;
 ```