@livekit/components-js-docs 0.1.47 → 0.1.49

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

@@ -9,6 +9,12 @@
 
 # usePagination
 
+{% callout type="note" variation="normal" %}
+
+This feature is experimental and may change or be removed based on developer feedback and real-world usage.
+
+{% /callout %}
+
 The `usePagination` hook implements simple pagination logic for use with arrays.
 
 ## Import
@@ -26,8 +32,6 @@ 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 %}

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

@@ -23,14 +23,12 @@ import { useParticipantAttribute } from "@livekit/components-react";
 const myAttributeValue = useParticipantAttribute("targetAttributeName");
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
 {% parameter name="attributeKey" type="string" optional=false %}
 {% /parameter %}
 
-{% parameter name="options" type="UseParticipantAttributesOptions" optional=true %}
+{% parameter name="options.participant" type="Participant" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -15,11 +15,9 @@
 import { useParticipantAttributes } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="props" type="UseParticipantAttributesOptions" optional=true %}
+{% parameter name="props.participant" type="Participant" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -17,8 +17,6 @@ Ensures that a participant is provided via context. If not inside a `Participant
 import { useParticipantContext } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Returns
 
 ```typescript

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

@@ -15,11 +15,9 @@
 import { useParticipantInfo } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="props" type="UseParticipantInfoOptions" optional=true %}
+{% parameter name="props.participant" type="Participant" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -15,11 +15,9 @@
 import { useParticipantPermissions } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="options" type="UseParticipantPermissionsOptions" optional=true %}
+{% parameter name="options.participant" type="Participant" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -30,11 +30,16 @@ const participants = useParticipants();
 </ParticipantLoop>;
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
-{% parameter name="options" type="UseParticipantsOptions" optional=true %}
+{% parameter name="options.room" type="Room" optional=true %}
+The room to use. If not provided, the hook will use the room from the context.
+
+{% /parameter %}
+
+{% parameter name="options.updateOnlyOn" type="RoomEvent[]" optional=true %}
+To optimize performance, you can use the `updateOnlyOn` property to decide on what RoomEvents the hook updates. By default it updates on all relevant RoomEvents to keep the returned participants array up to date. The minimal set of non-overwriteable `RoomEvents` is: `[RoomEvent.ParticipantConnected, RoomEvent.ParticipantDisconnected, RoomEvent.ConnectionStateChanged]`
+
 {% /parameter %}
 
 ## Returns

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

@@ -21,20 +21,18 @@ import { useParticipantTile } from "@livekit/components-react";
 
 The returned props include many data attributes that are useful for CSS styling purposes because they indicate the state of the participant and the track. For example: `data-lk-audio-muted`<!-- -->, `data-lk-video-muted`<!-- -->, `data-lk-speaking`<!-- -->, `data-lk-local-participant`<!-- -->, `data-lk-source`<!-- -->, `data-lk-facing-mode`<!-- -->.
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="htmlProps" type="React.HTMLAttributes<T>" optional=false %}
+{% parameter name="{ trackRef, onParticipantClick, disableSpeakingIndicator, htmlProps, }.htmlProps" type="React.HTMLAttributes<T>" optional=false %}
 {% /parameter %}
 
-{% parameter name="disableSpeakingIndicator" type="boolean" optional=true %}
+{% parameter name="{ trackRef, onParticipantClick, disableSpeakingIndicator, htmlProps, }.disableSpeakingIndicator" type="boolean" optional=true %}
 {% /parameter %}
 
-{% parameter name="onParticipantClick" type="(event: ParticipantClickEvent) => void" optional=true %}
+{% parameter name="{ trackRef, onParticipantClick, disableSpeakingIndicator, htmlProps, }.onParticipantClick" type="(event: ParticipantClickEvent) => void" optional=true %}
 {% /parameter %}
 
-{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+{% parameter name="{ trackRef, onParticipantClick, disableSpeakingIndicator, htmlProps, }.trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
 The track reference to display.
 
 {% /parameter %}

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

@@ -17,8 +17,6 @@
 import { useParticipantTracks } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
 {% parameter name="sources" type="Track.Source[]" optional=false %}

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

@@ -9,6 +9,12 @@
 
 # usePersistentUserChoices
 
+{% callout type="note" variation="normal" %}
+
+This feature is experimental and may change or be removed based on developer feedback and real-world usage.
+
+{% /callout %}
+
 A hook that provides access to user choices stored in local storage, such as selected media devices and their current state (on or off), as well as the user name.
 
 ## Import
@@ -17,11 +23,21 @@ A hook that provides access to user choices stored in local storage, such as sel
 import { usePersistentUserChoices } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="options" type="UsePersistentUserChoicesOptions" optional=true %}
+{% parameter name="options.defaults" type="Partial<LocalUserChoices>" optional=true %}
+The default value to use if reading from local storage returns no results or fails.
+
+{% /parameter %}
+
+{% parameter name="options.preventLoad" type="boolean" optional=true %}
+Whether to prevent loading user choices from persistent storage and use `defaults` instead.
+
+{% /parameter %}
+
+{% parameter name="options.preventSave" type="boolean" optional=true %}
+Whether to prevent saving to persistent storage.
+
 {% /parameter %}
 
 ## Returns

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

@@ -27,8 +27,6 @@ To function properly, this hook must be called within a `LayoutContext`<!-- -->.
 const pinnedTracks = usePinnedTracks();
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
 {% parameter name="layoutContext" type="LayoutContextType" optional=true %}

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

@@ -15,8 +15,6 @@
 import { usePreviewDevice } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
 {% parameter name="deviceId" type="string" optional=false %}

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

@@ -9,19 +9,20 @@
 
 # usePreviewTracks
 
+{% callout type="note" variation="normal" %}
+
+This feature is experimental and may change or be removed based on developer feedback and real-world usage.
+
+{% /callout %}
+
 ## Import
 
 ```typescript
 import { usePreviewTracks } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="options" type="CreateLocalTracksOptions" optional=false %}
-{% /parameter %}
-
 {% parameter name="onError" type="(err: Error) => void" optional=true %}
 {% /parameter %}
 

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

@@ -27,14 +27,14 @@ To optimize performance, you can use the `updateOnlyOn` property to decide on wh
 const participant = useRemoteParticipant({ kind: ParticipantKind.Agent, identity: "myAgent" });
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
 {% parameter name="identifier" type="ParticipantIdentifier" optional=false %}
 {% /parameter %}
 
-{% parameter name="options" type="UseRemoteParticipantOptions" optional=true %}
+{% parameter name="options.updateOnlyOn" type="ParticipantEvent[]" optional=true %}
+To optimize performance, you can use the `updateOnlyOn` property to decide on what `ParticipantEvents` the hook updates. By default it updates on all relevant ParticipantEvents to keep the returned participant up to date.
+
 {% /parameter %}
 
 ## Returns

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

@@ -27,14 +27,14 @@ To optimize performance, you can use the `updateOnlyOn` property to decide on wh
 const participant = useRemoteParticipant("Russ");
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
 {% parameter name="identity" type="string" optional=false %}
 {% /parameter %}
 
-{% parameter name="options" type="UseRemoteParticipantOptions" optional=true %}
+{% parameter name="options.updateOnlyOn" type="ParticipantEvent[]" optional=true %}
+To optimize performance, you can use the `updateOnlyOn` property to decide on what `ParticipantEvents` the hook updates. By default it updates on all relevant ParticipantEvents to keep the returned participant up to date.
+
 {% /parameter %}
 
 ## Returns

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

@@ -30,11 +30,16 @@ const participants = useRemoteParticipants();
 </ParticipantLoop>;
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
-{% parameter name="options" type="UseRemoteParticipantsOptions" optional=true %}
+{% parameter name="options.room" type="Room" optional=true %}
+The room to use. If not provided, the hook will use the room from the context.
+
+{% /parameter %}
+
+{% parameter name="options.updateOnlyOn" type="RoomEvent[]" optional=true %}
+To optimize performance, you can use the `updateOnlyOn` property to decide on what RoomEvents the hook updates. By default it updates on all relevant RoomEvents to keep the returned participants array up to date. The minimal set of non-overwriteable `RoomEvents` is: `[RoomEvent.ParticipantConnected, RoomEvent.ParticipantDisconnected, RoomEvent.ConnectionStateChanged]`
+
 {% /parameter %}
 
 ## Returns

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

@@ -17,8 +17,6 @@ Ensures that a room is provided via context. If no room is provided, an error is
 import { useRoomContext } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Returns
 
 ```typescript

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

@@ -15,11 +15,9 @@
 import { useRoomInfo } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="options" type="UseRoomInfoOptions" optional=true %}
+{% parameter name="options.room" type="Room" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -17,8 +17,6 @@ The `useSortedParticipants` hook returns the participants sorted by importance.
 import { useSortedParticipants } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
 {% parameter name="participants" type="Array<Participant>" optional=false %}

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

@@ -9,7 +9,7 @@
 
 # useSpeakingParticipants
 
-The `useSpeakingParticipants` hook returns the only the active speakers of all participants.
+The `useSpeakingParticipants` hook returns only the active speakers of all participants.
 
 ## Import
 
@@ -23,8 +23,6 @@ import { useSpeakingParticipants } from "@livekit/components-react";
 const activeSpeakers = useSpeakingParticipants();
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Returns
 
 ```typescript

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

@@ -9,6 +9,12 @@
 
 # useStartAudio
 
+{% callout type="note" variation="normal" %}
+
+This feature is experimental and may change or be removed based on developer feedback and real-world usage.
+
+{% /callout %}
+
 In many browsers to start audio playback, the user must perform a user-initiated event such as clicking a button. The `useStatAudio` hook returns an object with a boolean `canPlayAudio` flag that indicates whether audio playback is allowed in the current context, as well as a `startAudio` function that can be called in a button `onClick` callback to start audio playback in the current context.
 
 ## Import
@@ -17,14 +23,12 @@ In many browsers to start audio playback, the user must perform a user-initiated
 import { useStartAudio } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="props" type="React.ButtonHTMLAttributes<HTMLButtonElement>" optional=false %}
+{% parameter name="{ room, props }.props" type="React.ButtonHTMLAttributes<HTMLButtonElement>" optional=false %}
 {% /parameter %}
 
-{% parameter name="room" type="Room" optional=true %}
+{% parameter name="{ room, props }.room" type="Room" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -9,6 +9,12 @@
 
 # useStartVideo
 
+{% callout type="note" variation="normal" %}
+
+This feature is experimental and may change or be removed based on developer feedback and real-world usage.
+
+{% /callout %}
+
 In some browsers to start video playback in low power mode, the user must perform a user-initiated event such as clicking a button. The `useStartVideo` hook returns an object with a boolean `canPlayVideo` flag that indicates whether video playback is allowed in the current context, as well as a `startVideo` function that can be called in a button `onClick` callback to start video playback in the current context.
 
 ## Import
@@ -17,14 +23,12 @@ In some browsers to start video playback in low power mode, the user must perfor
 import { useStartVideo } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="props" type="React.ButtonHTMLAttributes<HTMLButtonElement>" optional=false %}
+{% parameter name="{ room, props }.props" type="React.ButtonHTMLAttributes<HTMLButtonElement>" optional=false %}
 {% /parameter %}
 
-{% parameter name="room" type="Room" optional=true %}
+{% parameter name="{ room, props }.room" type="Room" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -9,6 +9,12 @@
 
 # useSwipe
 
+{% callout type="note" variation="normal" %}
+
+This feature is experimental and may change or be removed based on developer feedback and real-world usage.
+
+{% /callout %}
+
 Simple implementation to detect horizontal swipe actions. Accepts callbacks for on right and left swipes.
 
 ## Import
@@ -27,16 +33,11 @@ import { useSwipe } from "@livekit/components-react";
     >
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
 {% parameter name="element" type="React.RefObject<HTMLElement>" optional=false %}
 {% /parameter %}
 
-{% parameter name="options" type="UseSwipeOptions" optional=true %}
-{% /parameter %}
-
 ## Returns
 
 ```typescript

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

@@ -23,8 +23,6 @@ import { useToken } from "@livekit/components-react";
 const token = useToken(<token-endpoint>, roomName, { userInfo: { identity, name }});
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
 {% parameter name="roomName" type="string" optional=false %}
@@ -33,7 +31,7 @@ const token = useToken(<token-endpoint>, roomName, { userInfo: { identity, name
 {% parameter name="tokenEndpoint" type="string | undefined" optional=false %}
 {% /parameter %}
 
-{% parameter name="options" type="UseTokenOptions" optional=true %}
+{% parameter name="options.userInfo" type="UserInfo" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -17,8 +17,6 @@ This function `useTrackByName` allows you to access a track by referencing its t
 import { useTrackByName } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
 {% parameter name="name" type="string" optional=false %}

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

@@ -23,8 +23,6 @@ import { useTrackMutedIndicator } from "@livekit/components-react";
 const { isMuted } = useTrackMutedIndicator(trackRef);
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
 {% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}

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

@@ -17,8 +17,6 @@ Ensures that a track reference is provided via context. If not inside a `TrackRe
 import { useTrackRefContext } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Returns
 
 ```typescript

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

@@ -17,14 +17,16 @@ The `useTracks` hook returns an array of `TrackReference` or `TrackReferenceOrPl
 import { useTracks } from "@livekit/components-react";
 ```
 
-## Usage Example 1
+## Usage
+
+### Example 1
 
 ```ts
 // Return all camera track publications.
 const trackReferences: TrackReference[] = useTracks([Track.Source.Camera]);
 ```
 
-## Usage Example 2
+### Example 2
 
 ```ts
 // Return all subscribed camera tracks as well as placeholders for
@@ -34,13 +36,8 @@ const trackReferencesWithPlaceholders: TrackReferenceOrPlaceholder[] = useTracks
 ]);
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 2} /%}
-
 ## Properties
 
-{% parameter name="options" type="UseTracksOptions" optional=true %}
-{% /parameter %}
-
 {% parameter name="sources" type="T" optional=true %}
 {% /parameter %}
 

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

@@ -24,8 +24,6 @@ const { buttonProps, enabled } = useTrackToggle(trackRef);
 return <button {...buttonProps}>{enabled ? "disable" : "enable"}</button>;
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Returns
 
 ```typescript

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

@@ -9,24 +9,37 @@
 
 # useTrackTranscription
 
+{% callout type="note" variation="normal" %}
+
+This feature is experimental and may change or be removed based on developer feedback and real-world usage.
+
+{% /callout %}
+
 ## Import
 
 ```typescript
 import { useTrackTranscription } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
 {% parameter name="trackRef" type="TrackReferenceOrPlaceholder | undefined" optional=false %}
 {% /parameter %}
 
-{% parameter name="options" type="TrackTranscriptionOptions" optional=true %}
+{% parameter name="options.bufferSize" type="number" optional=true %}
+how many transcription segments should be buffered in state
+
+{% /parameter %}
+
+{% parameter name="options.onTranscription" type="(newSegments: TranscriptionSegment[]) => void" optional=true %}
+optional callback for retrieving newly incoming transcriptions only
+
 {% /parameter %}
 
 ## Returns
 
+An object consisting of `segments` with maximum length of opts.windowLength and `activeSegments` that are valid for the current track timestamp
+
 ```typescript
 {
     segments: ReceivedTranscriptionSegment[];

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

@@ -9,6 +9,12 @@
 
 # useTrackVolume
 
+{% callout type="note" variation="normal" %}
+
+This feature is experimental and may change or be removed based on developer feedback and real-world usage.
+
+{% /callout %}
+
 Hook for tracking the volume of an audio track using the Web Audio API.
 
 ## Import
@@ -17,13 +23,8 @@ Hook for tracking the volume of an audio track using the Web Audio API.
 import { useTrackVolume } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
-
 ## Properties
 
-{% parameter name="options" type="AudioAnalyserOptions" optional=true %}
-{% /parameter %}
-
 {% parameter name="trackOrTrackReference" type="LocalAudioTrack | RemoteAudioTrack | TrackReference" optional=true %}
 {% /parameter %}
 

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

@@ -28,8 +28,6 @@ const trackRefs = useTracks();
 const updatedTrackRefs = useVisualStableUpdate(trackRefs, itemPerPage);
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Properties
 
 {% parameter name="maxItemsOnPage" type="number" optional=false %}
@@ -38,7 +36,9 @@ const updatedTrackRefs = useVisualStableUpdate(trackRefs, itemPerPage);
 {% parameter name="trackReferences" type="TrackReferenceOrPlaceholder[]" optional=false %}
 {% /parameter %}
 
-{% parameter name="options" type="UseVisualStableUpdateOptions" optional=true %}
+{% parameter name="options.customSortFunction" type="(trackReferences: TrackReferenceOrPlaceholder[]) => TrackReferenceOrPlaceholder[]" optional=true %}
+Overwrites the default sort function.
+
 {% /parameter %}
 
 ## Returns

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

@@ -9,7 +9,11 @@
 
 # useVoiceAssistant
 
-> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+{% callout type="note" variation="normal" %}
+
+This feature is under active development and may change based on developer feedback and real-world usage.
+
+{% /callout %}
 
 This hook looks for the first agent-participant in the room.
 
@@ -29,8 +33,6 @@ This hook requires an agent running with livekit-agents &gt;<!-- -->= 0.9.0
 const { state, audioTrack, agentTranscriptions, agentAttributes } = useVoiceAssistant();
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 1} /%}
-
 ## Returns
 
 ```typescript