Choice UI Documentation

Basic

Basic: Shows the default markdown input usage.

- Demonstrates a simple markdown editor with toolbar and preview. - Use for basic markdown editing needs.

Keyboard Shortcuts

Keyboard Shortcuts: Demonstrates all supported keyboard shortcuts.

**Text Formatting:**

- `Cmd/Ctrl + B` — Bold text - `Cmd/Ctrl + I` — Italic text - `Cmd/Ctrl + K` — Insert link

**Code:**

- `Cmd/Ctrl + `` ` `` — Inline code - `Cmd/Ctrl + Shift + `` ` `` — Code block

**Structure:**

- `Cmd/Ctrl + Shift + .` — Blockquote - `Cmd/Ctrl + 1-6` — Heading levels (H1-H6)

**Mentions:**

- Type `@` followed by name to trigger mention menu - Use `↑/↓` to navigate, `Enter/Tab` to select, `Esc` to close

Without Preview

Without Preview: Shows markdown input without preview tab.

- Only shows the write mode with toolbar. - Useful when preview is not needed.

Only Preview

Only Preview: Shows markdown input with only preview tab.

- Only shows the preview tab. - Useful when users prefer to see the preview of the markdown content.

### Heading

**Bold text**

Without Toolbar

Without Toolbar: Shows markdown input without toolbar.

- Only shows the textarea and preview tabs. - Useful when users prefer keyboard shortcuts.

Read Only

Read Only: Shows markdown input in read-only mode.

- Displays content but prevents editing. - Useful for displaying formatted content.

### Heading

**Bold text** and *italic text*

- List item 1
- List item 2

Disabled

Disabled: Shows markdown input in disabled state.

- Prevents all interactions. - Useful for disabled form states.

Custom Height

Custom Height: Shows markdown input with custom minimum height.

- Allows customizing the editor height. - Useful for different layout requirements.

Empty

Empty: Shows markdown input with empty initial value.

- Demonstrates the placeholder functionality. - Useful for new content creation.

Custom Toolbar Actions

Custom Toolbar Actions: Shows markdown input with only specific toolbar actions.

- Demonstrates filtering toolbar actions using visibleActions prop on MdInput.Toolbar. - Only shows bold, italic, and code actions. - Useful when you want to limit available formatting options.

Lists Only

Lists Only: Shows markdown input with only list-related actions.

- Demonstrates toolbar with only list actions. - Hides text formatting actions. - Useful for structured content creation.

Git Hub Flavored Markdown

GitHub Flavored Markdown: Comprehensive test of all GitHub-supported Markdown formats.

- Headings (H1-H6) - Text formatting (bold, italic, strikethrough, inline code) - Lists (ordered, unordered, task lists) - Code blocks with syntax highlighting - Tables - Blockquotes - Links and images - Horizontal rules - Auto-links - Mentions and issue references - And more GitHub-specific features

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

---

## Text Formatting

**Bold text** and *italic text* and ***bold italic text***

~~Strikethrough text~~

`Inline code` and ```code block```

---

## Lists

### Unordered List

- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
- Item 3

### Ordered List

1. First item
2. Second item
3. Third item
   1. Nested ordered 3.1
   2. Nested ordered 3.2

### Task List

- [x] Completed task
- [ ] Incomplete task
- [x] Another completed task
- [ ] Another incomplete task

---

## Code Blocks

### JavaScript

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet("World"));
```

### TypeScript

```typescript
interface User {
  id: number;
  name: string;
  email: string;
}

const user: User = {
  id: 1,
  name: "John Doe",
  email: "john@example.com"
};
```

### JSON

```json
{
  "name": "package.json",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.0.0"
  }
}
```

---

## Tables

| Feature | Status | Notes |
|---------|--------|-------|
| Tables | ✅ | Fully supported |
| Alignment | ✅ | Left, center, right |
| Styling | ✅ | Customizable |

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left | Center | Right |
| Text | Text | Text |

---

## Blockquotes

> This is a blockquote.
> It can span multiple lines.

> Nested blockquotes
> > Are also supported
> > > With multiple levels

---

## Links and Images

[Link text](https://example.com)

[Link with title](https://example.com "Link title")

<https://example.com>

<user@example.com>

![Image alt text](https://via.placeholder.com/150 "Image title")

---

## Mentions and References

@username

#123

#issue-123

---

## Horizontal Rules

---

***

___

---

## Mixed Content

Here's a paragraph with **bold**, *italic*, `code`, and a [link](https://example.com).

1. First item with **bold text**
2. Second item with *italic text*
3. Third item with `inline code`

> Blockquote with **bold** and *italic* text
> 
> And a list:
> - Item 1
> - Item 2

---

## Special Characters

Escaped characters: \* \_ \` \# \[ \]

Math expressions: $E = mc^2$ and $\sum_{i=1}^{n} x_i$

---

## Complex Example

### Project README

This is a **sample project** demonstrating various Markdown features.

#### Features

- [x] Feature 1
- [x] Feature 2
- [ ] Feature 3 (in progress)

#### Installation

```bash
npm install
npm run dev
```

#### Usage

```typescript
import { Component } from './component';

const app = new Component();
app.init();
```

#### Contributing

> Please read our [contributing guidelines](CONTRIBUTING.md) before submitting a PR.

#### License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Note**: This example demonstrates all GitHub Flavored Markdown features supported by the component.

Custom Layout

Custom Layout: Shows markdown input with custom layout using compound components.

- Demonstrates reordering components and custom styling. - Use for unique design requirements.

Markdown supported

Custom Toolbar

Custom Toolbar: Shows markdown input with custom toolbar groups.

- Demonstrates how to create custom toolbar groups with different actions. - Groups are automatically separated by dividers. - Useful for creating specialized editing experiences.

Toolbar In Footer

Toolbar in Footer: Shows markdown input with toolbar placed in the footer.

- Demonstrates flexible component composition by moving toolbar to footer. - Useful for alternative layout designs where toolbar is at the bottom.

Custom Toolbar In Footer

Toolbar in Footer with Custom Actions: Shows markdown input with custom toolbar in footer.

- Demonstrates custom toolbar groups placed in the footer. - Useful for creating unique editing experiences with bottom-aligned controls.

Markdown supported

With Mentions

With Mentions: Shows markdown input with

Custom Mention Format

Custom Mention Format: Shows markdown input with custom mention insertion format.

- Demonstrates custom onSelect callback to format inserted text. - Inserts mentions with custom format including email. - Useful for custom mention syntax or formatting requirements.

Mentions With Filtering

Mentions with Filtering: Shows markdown input with mention filtering.

- Type @ followed by characters to filter mentions. - Menu updates in real-time as you type. - Useful for large lists of mentionable items.

Mentions In Existing Content

Mentions in Existing Content: Shows markdown input with mentions in existing content.

- Demonstrates mention functionality with pre-filled content. - Shows how mentions work alongside markdown formatting. - Useful for editing existing content with mentions.

Custom Mention Rendering

Custom Mention Rendering: Shows markdown input with custom mention rendering component.

- Demonstrates how to customize the appearance of

Mention Rendering In Various Formats

Mention Rendering in Various Formats: Shows how mentions are rendered in different markdown contexts.

- Mentions in headings, paragraphs, lists, blockquotes, and links. - Demonstrates that mentions work consistently across all markdown elements. - Useful for testing mention rendering in various content structures.

Mention With Allowed Domains

Mention with Allowed Domains: Shows markdown input with allowed URL prefixes for mention images and links.

- Demonstrates how to configure allowedPrefixes to whitelist specific URL prefixes. - The same prefix list applies to both links and images in markdown. - Useful when mention components use external URLs that need to be whitelisted.

Whitelist Security

URL Whitelist Security: Demonstrates URL prefix whitelisting for links and images.

**Security Feature:** For security reasons, URLs that are not in the whitelist will NOT be rendered. You must manually add trusted domain prefixes to `allowedPrefixes` prop.

**How it works:**

- Only URLs starting with whitelisted prefixes are rendered as clickable links or images - Non-whitelisted URLs are stripped or rendered as plain text - This prevents XSS attacks, phishing links, and malicious content

**Example whitelist:**

```tsx allowedPrefixes={[ "https://your-domain.com", "https://trusted-cdn.com", "https://api.dicebear.com" ]} ```

**Note:** This applies to both markdown links `[text](url)` and images `![alt](url)`.

Code Display

Code Display: Comprehensive demonstration of inline code and code blocks with syntax highlighting.

- Shows inline code with backticks. - Demonstrates multi-line code blocks with language-specific syntax highlighting. - Supports JavaScript, TypeScript, Python, JSON, HTML, CSS, Bash, and more. - Code blocks powered by Shiki with automatic theme detection. - Includes copy-to-clipboard functionality. - Useful for technical documentation, tutorials, and API references.

# Code Examples

## Inline Code

Use backticks for inline code: `const greeting = "Hello World"`

You can also use inline code in sentences, like `Array.map()` or `useState()`.

## Code Blocks

### JavaScript

```javascript
function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

console.log(fibonacci(10)); // 55
```

### TypeScript

```typescript
interface User {
  id: number;
  name: string;
  email: string;
  createdAt: Date;
}

function createUser(data: Omit<User, 'id' | 'createdAt'>): User {
  return {
    ...data,
    id: Date.now(),
    createdAt: new Date(),
  };
}

const user = createUser({
  name: "John Doe",
  email: "john@example.com"
});
```

### React Component (TSX)

```tsx
import React, { useState } from 'react';
import { Button } from '@choice-ui/react';

export function Counter() {
  const [count, setCount] = useState(0);

return (
    <div className="flex items-center gap-4">
      <Button onClick={() => setCount(count - 1)}>-</Button>
      <span className="text-xl font-bold">{count}</span>
      <Button onClick={() => setCount(count + 1)}>+</Button>
    </div>
  );
}
```

### Python

```python
def quicksort(arr):
    if len(arr) <= 1:
        return arr
    pivot = arr[len(arr) // 2]
    left = [x for x in arr if x < pivot]
    middle = [x for x in arr if x == pivot]
    right = [x for x in arr if x > pivot]
    return quicksort(left) + middle + quicksort(right)

numbers = [3, 6, 8, 10, 1, 2, 1]
print(quicksort(numbers))
```

### JSON

```json
{
  "name": "@choice-ui/react",
  "version": "1.0.3",
  "description": "Desktop-first UI component library built for professional desktop applications",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "test": "vitest"
  },
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  }
}
```

### HTML

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My App</title>
</head>
<body>
  <div id="root"></div>
  <script src="/main.js"></script>
</body>
</html>
```

### CSS

```css
.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
}

.button {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  border: none;
  border-radius: 0.5rem;
  padding: 0.75rem 1.5rem;
  font-weight: 600;
  cursor: pointer;
  transition: transform 0.2s;
}

.button:hover {
  transform: translateY(-2px);
}
```

### Bash/Shell

```bash
#!/bin/bash

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test
```

### SQL

```sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO users (name, email) 
VALUES ('John Doe', 'john@example.com');

SELECT * FROM users WHERE email LIKE '%@example.com';
```

### Diff

```diff
  function calculate(a, b) {
-   return a + b
+   return a * b
  }

- const result = calculate(2, 3) // 5
+ const result = calculate(2, 3) // 6
```

## Code with Comments

```javascript
// This is a comment
const API_URL = 'https://api.example.com';

/**
 * Fetches user data from the API
 * @param {string} userId - The user ID to fetch
 * @returns {Promise<User>} The user data
 */
async function fetchUser(userId) {
  const response = await fetch(`${API_URL}/users/${userId}`);
  return response.json();
}

// Call the function
fetchUser('123').then(user => console.log(user));
```