Skip to content

feat(theme): scoped theming with ThemeScope component #768

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
rohilsurana merged 16 commits into from
May 27, 2026
Merged

feat(theme): scoped theming with ThemeScope component #768

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
64e762a
feat(theme): scoped theming with ThemeScope component
paanSinghCoder Apr 30, 2026
18a4060
Merge branch 'main' into feat/scoped-theming
paanSinghCoder May 15, 2026
c54ada3
refactor(theme-provider): unify ThemeScope into nested ThemeProvider
paanSinghCoder May 15, 2026
57c69d5
feat(theme): introduce Theme component and enhance theme overrides ex…
paanSinghCoder May 18, 2026
c166218
test(theme-provider): enhance tests for ThemeProvider and useTheme fu…
paanSinghCoder May 18, 2026
3cf4ba4
chore(www): remove scoped-theme example in favor of theme-overrides
paanSinghCoder May 19, 2026
00449b0
feat(theme): persistent scoped theming via storageKey
paanSinghCoder May 19, 2026
a51fef4
feat(theme): enhance theme overrides with persistent controls and sta…
paanSinghCoder May 19, 2026
9c94597
refactor(theme): consolidate theme tests into a single comprehensive …
paanSinghCoder May 19, 2026
888a8aa
fix(theme): restore :root fallback so tokens resolve without a <Theme>
paanSinghCoder May 19, 2026
471f1bd
Merge branch 'main' into feat/scoped-theming
paanSinghCoder May 19, 2026
7aba213
refactor(theme): rename ThemeProvider to Theme for improved clarity
paanSinghCoder May 25, 2026
5d465b2
refactor(theme): rename PersistedScope to Scoped and streamline theme…
paanSinghCoder May 26, 2026
9a3783b
feat(theme): enhance useTheme with scope targeting and improved conte…
paanSinghCoder May 26, 2026
7f081ed
docs(theme): update theme overview with inheritance rules and scope a…
paanSinghCoder May 26, 2026
904f55e
feat(typography): add modern style support with updated font-family v…
paanSinghCoder May 26, 2026
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
626 changes: 626 additions & 0 deletions apps/www/src/app/examples/theme-overrides/page.tsx
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion apps/www/src/components/theme-customiser/theme-customiser.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ export default function ThemeCustomizer() {
([key, value]) => DEFAULT_OPTIONS[key as keyof ThemeOptions] !== value
)
);
const themeString: string = `<ThemeProvider${getPropsString(props)}>`;
const themeString: string = `<Theme${getPropsString(props)}>`;

navigator.clipboard.writeText(themeString);
};
Expand Down
24 changes: 12 additions & 12 deletions apps/www/src/content/docs/(overview)/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,18 +32,18 @@ import "@raystack/apsara/style.css";

This single stylesheet includes all component styles and CSS custom properties (tokens) for theming.

### 2. Add ThemeProvider
### 2. Add Theme

Wrap your application with `ThemeProvider` to enable theming support:
Wrap your application with `Theme` to enable theming support:

```tsx
import { ThemeProvider } from "@raystack/apsara";
import { Theme } from "@raystack/apsara";

function App() {
return (
<ThemeProvider defaultTheme="system">
<Theme defaultTheme="system">
<YourApp />
</ThemeProvider>
</Theme>
);
}
```
Expand Down Expand Up @@ -78,23 +78,23 @@ Add the provider to your root layout:

```tsx
// app/layout.tsx
import { ThemeProvider } from "@raystack/apsara";
import { Theme } from "@raystack/apsara";
import "@raystack/apsara/style.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider defaultTheme="system">
<Theme defaultTheme="system">
{children}
</ThemeProvider>
</Theme>
</body>
</html>
);
}
```

The `suppressHydrationWarning` attribute is required because `ThemeProvider` injects a script to prevent theme flash during hydration.
The `suppressHydrationWarning` attribute is required because `Theme` injects a script to prevent theme flash during hydration.

### Vite

Expand All @@ -104,15 +104,15 @@ Add the provider to your main entry file:
// main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { ThemeProvider } from "@raystack/apsara";
import { Theme } from "@raystack/apsara";
import "@raystack/apsara/style.css";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<ThemeProvider defaultTheme="system">
<Theme defaultTheme="system">
<App />
</ThemeProvider>
</Theme>
</React.StrictMode>
);
```
Expand Down
8 changes: 4 additions & 4 deletions apps/www/src/content/docs/(overview)/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,14 @@ Apsara provides over 50 components organized by function:

## Theming

The theming system uses CSS custom properties (tokens) that automatically adapt to the active theme. Wrap your app with `ThemeProvider` to enable light/dark modes, accent colors, and style variants.
The theming system uses CSS custom properties (tokens) that automatically adapt to the active theme. Wrap your app with `Theme` to enable light/dark modes, accent colors, and style variants.

```tsx
import { ThemeProvider } from "@raystack/apsara";
import { Theme } from "@raystack/apsara";

<ThemeProvider defaultTheme="system" accentColor="indigo">
<Theme defaultTheme="system" accentColor="indigo">
<App />
</ThemeProvider>
</Theme>
```

Tokens follow a consistent naming convention:
Expand Down
2 changes: 1 addition & 1 deletion apps/www/src/content/docs/(overview)/styling.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Common data attributes include `data-open`, `data-closed`, `data-active`, `data-

## Theming with Data Attributes

The `ThemeProvider` sets data attributes on the root `<html>` element. Use these to conditionally style elements based on the active theme:
The `Theme` component sets data attributes on the root `<html>` element. Use these to conditionally style elements based on the active theme:

```css
/* Dark mode specific styles */
Expand Down
Loading
Loading