LiveKit Components JS

LiveKit provides a wide range of SDKs, UI components, and starter applications across different platforms:

UI Components

• React (Primary implementation in this repo)
• Android Compose
• SwiftUI
• Flutter

SDKs

• Agents SDKs: Python, Node.js
• LiveKit Client SDKs: Browser, Swift, Android, Flutter, React Native, Rust, Node.js, Python, Unity, Unity (WebGL), ESP32, C++
• Server APIs: Node.js, Golang, Ruby, Java/Kotlin, Python, Rust, PHP (community), .NET (community)

Starter Applications

• Python Agent, TypeScript Agent, React App, SwiftUI App, Android App, Flutter App, React Native App, Web Embed

Resources

• Official Docs
• LiveKit Cloud
• LiveKit CLI

The livekit/components-js repository is organized as a monorepo containing framework-specific implementations, core logic, and examples. Use the following structure to find relevant packages:

• Framework Implementations: The primary React implementation is located in packages/react/.
• Examples: Reference the Next.js example in examples/nextjs/.
• Internal Packages:
  • packages/core/: Core logic for components.
  • packages/styles/: Component styling.
  • packages/shadcn/: Shadcn-based components.

The @livekit/api-documenter tool is used to generate online API reference manuals for TypeScript libraries. It works by consuming *.api.json data files that have been produced by API Extractor.

Supported output formats include:

• Markdown
• DocFX

To use this tool, you must first configure API Extractor to generate the required .api.json files. For detailed configuration and usage instructions, refer to the API Extractor Generating Docs guide.

LiveKit Components Core is a wrapper around the livekit/client-sdk-js package. It transforms the event-based logic of the underlying SDK into observable state and component-level APIs.

Note: This is an internal package and is not intended to be used directly by end-users. Instead, you should use framework-specific implementations like @livekit/components-react.

LiveKit Components are designed with a multi-layered architecture to support multiple frameworks:

1. @livekit/components-core: This package contains the shared state handling logic. It uses observables as the primary data structure. This design allows the core logic to be easily ported to other frameworks like Solid (signals), Svelte (stores), Vue (composables), or Angular (observables).
2. Framework-specific packages: Packages like @livekit/components-react implement the core logic using framework-specific patterns (e.g., React Hooks and Context) to provide a native developer experience.

This approach avoids the use of Custom Elements (Web Components) as the primary implementation to ensure developers can work within the constraints and idiomatic patterns of their chosen framework.

Agents UI components are designed to be highly extensible:

• Prop Passthrough: Most components extend standard HTML attributes. For example, AgentControlBar extends HTMLAttributes<HTMLDivElement>, allowing you to pass any standard div props (like className, id, onClick, etc.) directly to the component.
• Direct Source Access: Since components are installed directly into your components/agents-ui directory, you can modify the source code to change logic or structure.
• Styling: For visual changes, it is recommended to pass Tailwind CSS classes to override default styles rather than editing the component internals where possible.
• Safe Updates: If you rerun the npx shadcn@latest add @agents-ui/{component-name} command, the CLI will prompt you before overwriting any existing files, allowing you to preserve your custom changes.

To prevent CSS collisions, all selectors used by LiveKit Components (classes, CSS variables, and custom data attributes) are prefixed. This prefixing is handled automatically via PostCSS plugins during the build step.

When writing or inspecting styles, you should be aware of how the prefix (e.g., lk) is applied to various elements:

• Classes: .button becomes .lk-button
• CSS Variables: --border-color becomes --lk-border-color
• Variable usage: var(--fg) becomes var(--lk-fg)
• Data Attributes: [data-active='false'] becomes [data-lk-active='false']
• Pseudo-selectors with attributes: &[data-muted='true'] becomes &[data-lk-muted='true']

Note: The attr() function is currently not supported for prefixing (e.g., attr(data-participant-name) remains unchanged and does not become attr(data-lk-participant-name)).

To run the Next.js example application, you must first follow the monorepo setup instructions at the root of the repository to ensure all local dependencies are linked.

1. Create a .env.local file by copying the contents of .env.example and update the values to match your LiveKit server configuration.
2. From the root of the monorepo, execute the development command.
3. Access the application at http://localhost:3000/ to view the available examples.

pnpm dev:next