Polymorphism

All component parts that render a DOM element have an as prop.

The as prop

For simple use cases the as prop can be used, either with native HTML elements or custom Solid components:

tsx
import { Tabs } from "@kobalte/core/tabs";
import { MyCustomButton } from "./components";
function App() {
	return (
		<Tabs>
			<Tabs.List>
				{/* Render an anchor tag instead of the default button */}
				<Tabs.Trigger value="one" as="a">
					A Trigger
				</Tabs.Trigger>
				{/* Render MyCustomButton instead of the default button */}
				<Tabs.Trigger value="one" as={MyCustomButton}>
					Custom Button Trigger
				</Tabs.Trigger>
			</Tabs.List>
			<Tabs.Content value="one">Content one</Tabs.Content>
		</Tabs>
	);
}

tsx
import { Tabs } from "@kobalte/core/tabs";
import { MyCustomButton } from "./components";
function App() {
	return (
		<Tabs>
			<Tabs.List>
				{/* Render an anchor tag instead of the default button */}
				<Tabs.Trigger value="one" as="a">
					A Trigger
				</Tabs.Trigger>
				{/* Render MyCustomButton instead of the default button */}
				<Tabs.Trigger value="one" as={MyCustomButton}>
					Custom Button Trigger
				</Tabs.Trigger>
			</Tabs.List>
			<Tabs.Content value="one">Content one</Tabs.Content>
		</Tabs>
	);
}

The as prop callback

For more advanced use cases the as prop can accept a callback. The main reason to use a callback over the normal as prop is being able to set props without interfering with Kobalte.

When using this pattern the following rules apply to the callback:

• You must spread the props forwarded to your callback onto your node/component.
• Custom props are passed as is from the parent.
• Kobalte options are not passed to the callback, only the resulting html attributes.
• You should set your event handlers on the parent and not inside your callback.

tsx
import { Tabs } from "@kobalte/core/tabs";
import { MyCustomButton } from "./components";
function App() {
	return (
		<Tabs>
			<Tabs.List>
				{/* The `value` prop is used by Kobalte and not passed to MyCustomButton */}
				<Tabs.Trigger value="one" as={MyCustomButton}>
					A Trigger
				</Tabs.Trigger>
				{/* The `value` prop is used by Kobalte and not passed to MyCustomButton */}
				<Tabs.Trigger
					value="one"
					as={props => (
						// The `value` prop is directly passed to MyCustomButton
						<MyCustomButton value="custom" {...props} />
					)}
				>
					Custom Button Trigger
				</Tabs.Trigger>
			</Tabs.List>
			<Tabs.Content value="one">Content one</Tabs.Content>
		</Tabs>
	);
}

tsx
import { Tabs } from "@kobalte/core/tabs";
import { MyCustomButton } from "./components";
function App() {
	return (
		<Tabs>
			<Tabs.List>
				{/* The `value` prop is used by Kobalte and not passed to MyCustomButton */}
				<Tabs.Trigger value="one" as={MyCustomButton}>
					A Trigger
				</Tabs.Trigger>
				{/* The `value` prop is used by Kobalte and not passed to MyCustomButton */}
				<Tabs.Trigger
					value="one"
					as={props => (
						// The `value` prop is directly passed to MyCustomButton
						<MyCustomButton value="custom" {...props} />
					)}
				>
					Custom Button Trigger
				</Tabs.Trigger>
			</Tabs.List>
			<Tabs.Content value="one">Content one</Tabs.Content>
		</Tabs>
	);
}

You can optionally use a type helper to get the exact types passed to your callback:

tsx
import { Tabs, TabsTriggerOptions, TabsTriggerRenderProps } from "@kobalte/core/tabs";
import { PolymorphicCallbackProps } from "@kobalte/core/polymorphic";
<Tabs.Trigger
	value="one"
	as={(
		props: PolymorphicCallbackProps<
			MyCustomButtonProps,
			TabsTriggerOptions,
			TabsTriggerRenderProps
		>,
	) => (
		// The `value` prop is directly passed to MyCustomButton
		<MyCustomButton value="custom" {...props} />
	)}
>
	Custom Button Trigger
</Tabs.Trigger>;

tsx
import { Tabs, TabsTriggerOptions, TabsTriggerRenderProps } from "@kobalte/core/tabs";
import { PolymorphicCallbackProps } from "@kobalte/core/polymorphic";
<Tabs.Trigger
	value="one"
	as={(
		props: PolymorphicCallbackProps<
			MyCustomButtonProps,
			TabsTriggerOptions,
			TabsTriggerRenderProps
		>,
	) => (
		// The `value` prop is directly passed to MyCustomButton
		<MyCustomButton value="custom" {...props} />
	)}
>
	Custom Button Trigger
</Tabs.Trigger>;

Event lifecycle

Setting custom event handlers on component will call your custom handler before Kobalte's.

Types

This section is mainly for library author that want to build on top of Kobalte and expose the correct types to your end users.

Every component that renders an HTML element has the following types:

• ComponentOptions
• ComponentCommonProps<T>
• ComponentRenderProps
• ComponentProps<T>

For example, Tabs.Trigger has the types TabsTriggerOptions, TabsTriggerCommonProps<T>, TabsTriggerRenderProps and TabsTriggerProps<T>.

Components themselves accept props as PolymorphicProps<T, ComponentProps> where T is a generic that extends ValidComponent and ComponentProps are the props of the Kobalte component. This type allows components to accept Kobalte's props and all other props accepted by T.

ComponentOptions

This type contains all custom props consumed by Kobalte, these props do not exist in HTML. These are not passed to the HTML element nor to the as callback.

ComponentCommonProps<T>

This type contains HTML attributes optionally accepted by the Kobalte component and will be forwarded to the rendered DOM node. These are managed by Kobalte but can be customized by the end user. It includes attributes such as id, ref, event handlers, etc. The generic is used by ref and event handlers, by default it is HTMLElement.

ComponentRenderProps

This type extends ComponentCommonProps and additionally contains attributes that are passed to the DOM node and fully managed by Kobalte. You should never assign these yourself or set them on the Kobalte component. Modifying these props will break your component's behavior and accessibity.

ComponentProps<T>

This is the final type exported by components, it is equal to ComponentOptions & Partial<ComponentCommonProps>. It combines all props expected by Kobalte's component. The generic is used by the CommonProps, by default it is HTMLElement.

PolymorphicProps<T, ComponentProps>

If you're writing a custom component and want to expose Kobalte's as prop to the end user and keep proper typing, be sure to use PolymorphicProps<T, ComponentProps> for your props type.

tsx
import { Tabs, TabsTriggerProps } from "@kobalte/core/tabs";
import { PolymorphicProps } from "@kobalte/core/polymorphic";
// Optionally extend `TabsTriggerProps` if you wish to
// expose Kobalte props to your end user.
interface CustomProps<T extends ValidComponent = "button"> extends TabsTriggerProps<T> {
	variant: "default" | "outline";
}
// Your generic `T` should extend ValidComponent and have a default value of the default DOM node.
function CustomTabsTrigger<T extends ValidComponent = "button">(
	props: PolymorphicProps<T, CustomProps<T>>,
) {
	// Typescript degrades typechecking when using generics, as long as we
	// spread `others` to our element, we can effectively ignore them.
	const [local, others] = splitProps(props as CustomProps, ["variant"]);
	return (
		<Tabs.Trigger
			// Optional, will default to Kobalte otherwise.
			// This should match with your generic `T` default.
			as="button"
			class={local.variant === "default" ? "default-trigger" : "outline-trigger"}
			// Make sure to spread these props!
			{...others}
		/>
	);
}

tsx
import { Tabs, TabsTriggerProps } from "@kobalte/core/tabs";
import { PolymorphicProps } from "@kobalte/core/polymorphic";
// Optionally extend `TabsTriggerProps` if you wish to
// expose Kobalte props to your end user.
interface CustomProps<T extends ValidComponent = "button"> extends TabsTriggerProps<T> {
	variant: "default" | "outline";
}
// Your generic `T` should extend ValidComponent and have a default value of the default DOM node.
function CustomTabsTrigger<T extends ValidComponent = "button">(
	props: PolymorphicProps<T, CustomProps<T>>,
) {
	// Typescript degrades typechecking when using generics, as long as we
	// spread `others` to our element, we can effectively ignore them.
	const [local, others] = splitProps(props as CustomProps, ["variant"]);
	return (
		<Tabs.Trigger
			// Optional, will default to Kobalte otherwise.
			// This should match with your generic `T` default.
			as="button"
			class={local.variant === "default" ? "default-trigger" : "outline-trigger"}
			// Make sure to spread these props!
			{...others}
		/>
	);
}

If you do not wish to allow changing the element type, you can simplify your types by making props: OverrideComponentProps<"button", CustomProps>, replace "button" with the correct tagname for other components, imported from "@kobalte/utils".

If you also want to export exact types, you can re-export and extends component types:

tsx
export interface CustomTabsTriggerOptions extends TabsTriggerOptions {
	variant: "default" | "outline";
}
export interface CustomTabsTriggerCommonProps<T extends HTMLElement = HTMLElement> extends TabsTriggerCommonProps<T> {
	// If you allow users to set classes and extend them.
	//class: string;
}
export interface CustomTabsTriggerRenderProps
	extends CustomTabsTriggerCommonProps,
		TabsTriggerRenderProps {
	// If you do not allow users to set classes and manage all of them.
	class: string;
}
export type CustomTabsTriggerProps<T extends ValidComponent = "button"> = CustomTabsTriggerOptions &
	Partial<CustomTabsTriggerCommonProps<ElementOf<T>>>;
export function CustomTabsTrigger<T extends ValidComponent = "button">(
	props: PolymorphicProps<T, CustomTabsTriggerProps<T>,
) {}

tsx
export interface CustomTabsTriggerOptions extends TabsTriggerOptions {
	variant: "default" | "outline";
}
export interface CustomTabsTriggerCommonProps<T extends HTMLElement = HTMLElement> extends TabsTriggerCommonProps<T> {
	// If you allow users to set classes and extend them.
	//class: string;
}
export interface CustomTabsTriggerRenderProps
	extends CustomTabsTriggerCommonProps,
		TabsTriggerRenderProps {
	// If you do not allow users to set classes and manage all of them.
	class: string;
}
export type CustomTabsTriggerProps<T extends ValidComponent = "button"> = CustomTabsTriggerOptions &
	Partial<CustomTabsTriggerCommonProps<ElementOf<T>>>;
export function CustomTabsTrigger<T extends ValidComponent = "button">(
	props: PolymorphicProps<T, CustomTabsTriggerProps<T>,
) {}

ElementOf<T> is a helper from "@kobalte/core/polymorphic" that converts a tag name into its element (e.g. ElementOf<"button"> = HTMLButtonElement).