TypeScript Usage

@mintlify/components is written in TypeScript and exports comprehensive type definitions for all components, props, and utilities.

Type Definitions

All types are automatically included when you install the package. The package exports types at ./dist/index.d.ts which are automatically resolved by TypeScript.

package.json

{
  "dependencies": {
    "@mintlify/components": "^1.0.0"
  }
}

From source/packages/components/package.json:8:

"types": "./dist/index.d.ts"

Component Prop Types

Every component exports its prop types for type-safe usage. All types are exported from the main package entry point.

Accordion

import type { AccordionProps, AccordionGroupProps } from '@mintlify/components';

// From source/packages/components/src/components/accordion/accordion.tsx:20-48
type AccordionProps = {
  title: ReactNode;              // Prefer string for URL state sync
  description?: string;
  defaultOpen: boolean;
  icon?: ReactNode | string;
  iconType?: IconType;
  children: ReactNode;
  className?: string;
  trackOpen?: (event: { title: string }) => void;
  trackClose?: (event: { title: string }) => void;
  topOffset?: string;
};

const MyAccordion: React.FC<AccordionProps> = (props) => {
  return <Accordion {...props} />;
};

Badge

import type { 
  BadgeProps, 
  BadgeColor, 
  BadgeShape, 
  BadgeSize,
  BadgeVariant 
} from '@mintlify/components';

// From source/packages/components/src/components/badge/badge.tsx:6-20
type BadgeSize = "xs" | "sm" | "md" | "lg";
type BadgeShape = "rounded" | "pill";
type BadgeVariant = "solid" | "outline";
type BadgeColor =
  | "gray" | "blue" | "green" | "orange" | "yellow" | "red" | "purple"
  | "white" | "surface" | "white-destructive" | "surface-destructive";

const color: BadgeColor = 'blue';
const shape: BadgeShape = 'rounded';
const size: BadgeSize = 'md';

<Badge color={color} shape={shape} size={size} variant="solid">
  TypeScript
</Badge>

Callout

import type { CalloutProps, CalloutVariant } from '@mintlify/components';

// From source/packages/components/src/components/callout/callout.tsx:16-34
type CalloutVariant =
  | "info"
  | "warning"
  | "note"
  | "tip"
  | "check"
  | "danger"
  | "custom";

type CalloutProps = {
  children: ReactNode;
  variant?: CalloutVariant;
  icon?: ReactNode | string;
  iconType?: IconType;
  iconLibrary?: IconLibrary;
  color?: string;
  className?: string;
  ariaLabel?: string;
};

<Callout variant="info" icon="info-circle" color="#3b82f6">
  Type-safe callout configuration
</Callout>

Card

import type { 
  CardProps, 
  CardPropsBase,
  CardComponentProps,
  CardIconProps 
} from '@mintlify/components';

const cardProps: CardProps = {
  title: 'Getting Started',
  icon: 'rocket',
  href: '/docs/getting-started',
};

<Card {...cardProps} />

Code Block

import type { CodeBlockProps, BaseCodeBlockProps } from '@mintlify/components';

const codeProps: CodeBlockProps = {
  code: 'console.log("Hello");',
  language: 'javascript',
  showLineNumbers: true,
};

<CodeBlock {...codeProps} />

CodeGroup

import type { CodeGroupProps } from '@mintlify/components';

const groupProps: CodeGroupProps = {
  children: [
    <CodeBlock key="js" code="console.log('Hi');" language="javascript" />,
    <CodeBlock key="py" code="print('Hi')" language="python" />,
  ],
};

<CodeGroup {...groupProps} />

Icon

import type { IconProps } from '@mintlify/components';
import type { IconType, IconLibrary } from '@mintlify/components';

// From source/packages/components/src/utils/icon-utils.ts:44-62
const ICON_TYPES = [
  "brands", "duotone", "light", "regular",
  "sharp-duotone-solid", "sharp-light", "sharp-regular",
  "sharp-solid", "sharp-thin", "solid", "thin"
] as const;

type IconType = (typeof ICON_TYPES)[number];

const ICON_LIBRARIES = ["fontawesome", "lucide"] as const;
type IconLibrary = (typeof ICON_LIBRARIES)[number];

const iconProps: IconProps = {
  icon: 'github',
  iconType: 'regular',
  iconLibrary: 'fontawesome',
};

<Icon {...iconProps} />

Steps

import type { StepsProps, StepsItemProps, StepTitleSize } from '@mintlify/components';
import { STEP_TITLE_SIZES } from '@mintlify/components';

// STEP_TITLE_SIZES contains all valid title sizes
const titleSize: StepTitleSize = 'h3';

const stepProps: StepsItemProps = {
  title: 'Install Package',
  children: 'Run npm install',
};

Tabs

import type { TabsProps, TabsItemProps } from '@mintlify/components';

const tabsConfig: TabsProps = {
  children: [
    { label: 'JavaScript', content: <div>JS content</div> },
    { label: 'TypeScript', content: <div>TS content</div> },
  ],
};

import type { TooltipProps } from '@mintlify/components';

const tooltipProps: TooltipProps = {
  content: 'Helpful information',
  children: <button>Hover me</button>,
};

<Tooltip {...tooltipProps} />

Complete Type Exports

Here’s a comprehensive list of all exported types from the package:

Component Types
Utility Types

// All component prop types
import type {
  AccordionProps,
  AccordionGroupProps,
  BadgeProps,
  BadgeColor,
  BadgeShape,
  BadgeSize,
  BadgeVariant,
  CalloutProps,
  CalloutVariant,
  CardProps,
  CardPropsBase,
  CardComponentProps,
  CardIconProps,
  CodeBlockProps,
  BaseCodeBlockProps,
  CodeGroupProps,
  ColumnsProps,
  ColorProps,
  ExpandableProps,
  FrameProps,
  IconProps,
  MermaidProps,
  PanelProps,
  PropertyProps,
  StepsProps,
  StepsItemProps,
  StepTitleSize,
  TabsProps,
  TabsItemProps,
  TileProps,
  TooltipProps,
  TreeProps,
  UpdateProps,
  ViewProps,
} from '@mintlify/components';

// Icon and utility types
import type { 
  IconType,
  IconLibrary 
} from '@mintlify/components';

// The cn function (from clsx + tailwind-merge)
import { cn } from '@mintlify/components';

// Usage with ClassValue types
const className = cn(
  'base-class',
  condition && 'conditional-class',
  ['array', 'of', 'classes'],
  { 'class-name': true }
);

Type-Safe Variants

Many components use discriminated unions for type-safe variant props:

import { Callout } from '@mintlify/components';
import type { CalloutVariant } from '@mintlify/components';

// TypeScript knows which props are valid for each variant
function getCalloutConfig(variant: CalloutVariant) {
  switch (variant) {
    case 'info':
    case 'warning':
    case 'note':
    case 'tip':
    case 'check':
    case 'danger':
      // Preset variants - icon is automatically provided
      return { variant };
    case 'custom':
      // Custom variant requires icon and color
      return { variant, icon: 'star', color: '#fbbf24' };
  }
}

<Callout {...getCalloutConfig('info')}>
  Type-safe variant handling
</Callout>

Using the cn Utility

The cn utility function combines clsx and tailwind-merge for intelligent class name merging:

import { cn } from '@mintlify/components';

// From source/packages/components/src/utils/cn.ts
// Combines clsx and tailwind-merge

// All these are valid:
const classes = cn(
  'base-class',                          // string
  condition && 'conditional',            // conditional string
  { 'active': isActive },               // object
  ['array', 'of', 'classes'],           // array
  undefined,                             // undefined (ignored)
  null,                                  // null (ignored)
);

// Use with component props
interface Props {
  className?: string;
  isActive?: boolean;
}

const Component = ({ className, isActive }: Props) => (
  <div className={cn('base', isActive && 'active', className)}>
    Content
  </div>
);

Constants and Enums

Some components export constants for valid values:

import { STEP_TITLE_SIZES } from '@mintlify/components';
import type { StepTitleSize } from '@mintlify/components';

// STEP_TITLE_SIZES contains all valid title sizes
const validSizes: StepTitleSize[] = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];

function renderStep(titleSize: StepTitleSize) {
  // titleSize is constrained to valid values
  return <Steps titleSize={titleSize}>...</Steps>;
}

Generic Component Props

For components that accept generic React props:

import type { ComponentPropsWithoutRef } from 'react';
import { Badge } from '@mintlify/components';
import type { BadgeProps } from '@mintlify/components';

// Extend component props with additional HTML attributes
type ExtendedBadgeProps = BadgeProps & ComponentPropsWithoutRef<'div'>;

const MyBadge = (props: ExtendedBadgeProps) => {
  return <Badge {...props} />;
};

// Now you can use additional div props
<MyBadge 
  color="blue" 
  onClick={() => console.log('clicked')}
  data-testid="my-badge"
>
  Clickable
</MyBadge>

Type Inference

TypeScript can infer types from usage:

import { Card } from '@mintlify/components';

// Type is inferred from the component
const cards = [
  { title: 'Guide 1', icon: 'book', href: '/guide-1' },
  { title: 'Guide 2', icon: 'rocket', href: '/guide-2' },
] as const;

// TypeScript knows the shape of each card
cards.map((card) => (
  <Card key={card.href} {...card} />
));

Utility Type Helpers

Create helper types for common patterns:

import type { CalloutProps, CardProps } from '@mintlify/components';

// Extract specific prop types
type CalloutVariants = CalloutProps['variant'];
type CardIcons = CardProps['icon'];

// Create custom component types
type InfoCalloutProps = Omit<CalloutProps, 'variant'> & {
  variant: 'info';
};

const InfoCallout = (props: InfoCalloutProps) => (
  <Callout {...props} />
);

Working with Children

Type children props correctly:

import type { ReactNode } from 'react';
import { Accordion } from '@mintlify/components';

interface WrapperProps {
  children: ReactNode;
  title?: string;
}

const AccordionWrapper = ({ children, title }: WrapperProps) => (
  <Accordion title={title || 'Default Title'} defaultOpen={false}>
    {children}
  </Accordion>
);

tsconfig.json Configuration

Recommended TypeScript configuration for working with the library:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "types": ["node"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Type-Safe Component Composition

Build type-safe wrapper components:

import { Card, Callout } from '@mintlify/components';
import type { CardProps, CalloutProps } from '@mintlify/components';

interface FeatureCardProps extends Omit<CardProps, 'icon'> {
  status: 'stable' | 'beta' | 'deprecated';
}

function FeatureCard({ status, ...props }: FeatureCardProps) {
  const icons = {
    stable: 'check',
    beta: 'flask',
    deprecated: 'x',
  };

  return <Card {...props} icon={icons[status]} />;
}

// Usage is fully type-checked
<FeatureCard 
  title="New Feature"
  status="beta"  // Only accepts 'stable' | 'beta' | 'deprecated'
  href="/features"
/>

Advanced Pattern: Typed Component Factories

import type { BadgeProps, BadgeColor } from '@mintlify/components';
import { Badge } from '@mintlify/components';

// Create a type-safe badge factory
function createBadge(color: BadgeColor) {
  return (props: Omit<BadgeProps, 'color'>) => (
    <Badge {...props} color={color} />
  );
}

const BlueBadge = createBadge('blue');
const GreenBadge = createBadge('green');

// Usage
<BlueBadge size="md">TypeScript</BlueBadge>
<GreenBadge size="sm">Success</GreenBadge>

Troubleshooting

Type errors after installation

Ensure TypeScript version is 5.0 or higher
Run npm install to ensure types are properly installed
Restart your TypeScript language server (in VS Code: Cmd+Shift+P → “Restart TS Server”)
Check that node_modules/@mintlify/components/dist/index.d.ts exists

Cannot find module or type declarations

Check that:

@mintlify/components is in your dependencies (not devDependencies)
Your moduleResolution is set to bundler, node16, or nodenext in tsconfig.json
You’re importing from @mintlify/components (not from a subdirectory)

Prop types not autocompleting

Make sure you’re importing types correctly:

import { Component } from '@mintlify/components';
import type { ComponentProps } from '@mintlify/components';

The type keyword is recommended for type-only imports for better tree-shaking.

IconType or IconLibrary not found

These types are exported from the main package:

import type { IconType, IconLibrary } from '@mintlify/components';

They’re defined in source/packages/components/src/utils/icon-utils.ts.

Next Steps

Tailwind Integration

Set up Tailwind CSS with the components

Dark Mode

Configure dark mode theming

Getting Started

Core Concepts

Guides

Type Definitions

Component Prop Types

Accordion

Badge

Callout

Card

Code Block

CodeGroup

Icon

Steps

Tabs

Tooltip

Complete Type Exports

Type-Safe Variants

Using the cn Utility

Constants and Enums

Generic Component Props

Type Inference

Utility Type Helpers

Working with Children

tsconfig.json Configuration

Type-Safe Component Composition

Advanced Pattern: Typed Component Factories

Troubleshooting

Next Steps

Tailwind Integration

Dark Mode

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Documentation Index

​Type Definitions

​Component Prop Types

​Accordion

​Badge

​Callout

​Card

​Code Block

​CodeGroup

​Icon

​Steps

​Tabs

​Tooltip

​Complete Type Exports

​Type-Safe Variants

​Using the cn Utility

​Constants and Enums

​Generic Component Props

​Type Inference

​Utility Type Helpers

​Working with Children

​tsconfig.json Configuration

​Type-Safe Component Composition

​Advanced Pattern: Typed Component Factories

​Troubleshooting

​Next Steps

Tailwind Integration

Dark Mode

Build docs developers (and LLMs) love

Type Definitions

Component Prop Types

Accordion

Badge

Callout

Card

Code Block

CodeGroup

Icon

Steps

Tabs

Tooltip

Complete Type Exports

Type-Safe Variants

Using the cn Utility

Constants and Enums

Generic Component Props

Type Inference

Utility Type Helpers

Working with Children

tsconfig.json Configuration

Type-Safe Component Composition

Advanced Pattern: Typed Component Factories

Troubleshooting

Next Steps