Skip to content

Clarify global language synchronization for tabs and code blocks (Docs) #472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 18, 2025
Merged

Clarify global language synchronization for tabs and code blocks (Docs) #472

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
16b75b5
clarify language sync for tabs and code blocks
devalog Aug 15, 2025
f979951
add example without sync
devalog Aug 15, 2025
f47c3b8
change order of examples
devalog Aug 18, 2025
ae9a914
add in markdown examples
devalog Aug 18, 2025
687504f
Merge branch 'main' into global-lang-sync
devalog Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions fern/products/docs/pages/component-library/default-components/code-blocks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -306,9 +306,16 @@ The `CodeBlocks` component allows you to display multiple code blocks in a tabbe
</Tab>
</Tabs>

## Example of Synchronized Blocks
## Language synchronization

Multiple `CodeBlocks` on a page automatically synchronize, showing the same language across all blocks.
Multiple `CodeBlocks` on a documentation site automatically synchronize. This
means when a user selects a `CodeBlock` with a specific language, all other
`CodeBlocks` across your documentation site with the same language will
automatically sync and switch to match. Language preferences are stored in
client-side local storage and persist across browser sessions.

The example below demonstrates language sync in action – choosing a language in
either set of code blocks will automatically update both sets to match:

<CodeBlocks>
```python title="Python"
Expand Down Expand Up @@ -362,6 +369,10 @@ Multiple `CodeBlocks` on a page automatically synchronize, showing the same lang
```
</CodeBlocks>

<Note title="Tabs and CodeBlocks integration">
`CodeBlocks` automatically synchronize with [`<Tab>` components that have a `language` property](/docs/writing-content/components/tabs#language-synchronization).
</Note>

### Override synchronization

You can override the synchronization of code blocks by setting the `for` prop.
Expand Down
130 changes: 107 additions & 23 deletions fern/products/docs/pages/component-library/default-components/tabs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,9 @@
---
title: 'Tabs'
description: 'The Tabs component allows you to display related content in a tabbed view.'
title: Tabs
description: The Tabs component allows you to display related content in a tabbed view with support for language synchronization.
---

The Tabs component organizes content into separate tabs that users can switch between. Each tab can contain different types of content like examples or code snippets.

## Properties
<ParamField path="title" type="string" required={true}>
The title displayed in the tab header
</ParamField>

<ParamField path="language" type="string" required={false}>
The language associated with the code block. Any arbitrary string may be used.

When a user selects a tab with a specific language, all other tabs assigned to the same language will automatically sync and switch to match.
</ParamField>

<ParamField path="children" type="string | JSX" required={true}>
The content to be displayed when the tab is selected. Can include text, markdown, and components.
</ParamField>

<br />
The Tabs component organizes content into separate tabs that users can switch between. Each tab can contain different types of content like examples, code snippets, or documentation sections.

<Tabs>
<Tab title="First Tab">
Expand All @@ -34,8 +17,6 @@ The Tabs component organizes content into separate tabs that users can switch be
</Tab>
</Tabs>

<Aside>

<CodeBlock title="Markdown">
```jsx
<Tabs>
Expand All @@ -52,4 +33,107 @@ The Tabs component organizes content into separate tabs that users can switch be
```
</CodeBlock>

</Aside>
## Properties

<ParamField path="title" type="string" required={true}>
The title displayed in the tab header
</ParamField>

<ParamField path="language" type="string" required={false}>
The language associated with the code block. Any arbitrary string may be used.

When specified, enables global language synchronization across all tabs and code blocks with the same language value.
</ParamField>

<ParamField path="children" type="string | JSX" required={true}>
The content to be displayed when the tab is selected. Can include text, markdown, and components.
</ParamField>

## Language synchronization

Multiple `Tabs` with a `language` property automatically synchronize. This means
when a user selects a tab with a specific language, all other tabs across your
documentation site with the same language will automatically sync and switch to
match. Language preferences are stored in client-side local storage and persist
across browser sessions.

Tabs **without** the `language` property don't stay in sync with other tabs on your site. In the below example, choosing a language in
either set of tabs doesn't affect the other set of tabs:

<Tabs>
<Tab title="TypeScript">
```typescript
console.log("First code block!");
```
</Tab>
<Tab title="Python">
```python
print("First code block!")
```
</Tab>
<Tab title="Java">
```java
System.out.println("First code block!");
```
</Tab>
</Tabs>

<Tabs>
<Tab title="TypeScript">
```typescript
console.log("Second code block – this won't sync with the one above!");
```
</Tab>
<Tab title="Python">
```python
print("Second code block – this won't sync with the one above!")
```
</Tab>
<Tab title="Java">
```java
System.out.println("Second code block – this won't sync with the one above!");
```
</Tab>
</Tabs>

Compare this to tabs **with** the `language` property. Choosing a language in either set below will automatically update both sets to match:

<Tabs>
<Tab title="TypeScript" language="typescript">
```typescript
console.log("First code block!");
```
</Tab>
<Tab title="Python" language="python">
```python
print("First code block!")
```
</Tab>
<Tab title="Java" language="java">
```java
System.out.println("First code block!");
```
</Tab>
</Tabs>

<Tabs>
<Tab title="TypeScript" language="typescript">
```typescript
console.log("Second code block – language syncs with the one above!");
```
</Tab>
<Tab title="Python" language="python">
```python
print("Second code block – language syncs with the one above!")
```
</Tab>
<Tab title="Java" language="java">
```java
System.out.println("Second code block – language syncs with the one above!");
```
</Tab>
</Tabs>

Copy link
Contributor

@kgowru kgowru Aug 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@devalog I think we should add the markdown for both of these examples.

Also i think we should lead with the sync'd lanugage example and then the non-sync'd language example.

Copy link
Collaborator Author

@devalog devalog Aug 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I swapped the order. I agree about having markdown examples, but I keep getting mdx parsing errors when I try to do this. I don't think the parser is liking the nested code fences. Any ideas?


```jsx
<Tabs>
  <Tab title="TypeScript" language="typescript">
    ```typescript
    console.log("Second code block – language syncs with the one above!");
    ```
  </Tab>
  <Tab title="Python" language="python">
    ```python
    print("Second code block – language syncs with the one above!")
    ```
  </Tab>
  <Tab title="Java" language="java">
    ```java
    System.out.println("Second code block – language syncs with the one above!");
    ```
  </Tab>
</Tabs>

<Note title="Tabs and CodeBlocks integration">
Language-enabled `Tabs` automatically synchronize with [`CodeBlocks` in that same language](/docs/writing-content/components/code-blocks#language-synchronization).
</Note>