https://github.com/ericrav/theme-party
React theme provider: swap styles or entire component layouts
https://github.com/ericrav/theme-party
react theme typescript
Last synced: 5 months ago
JSON representation
React theme provider: swap styles or entire component layouts
- Host: GitHub
- URL: https://github.com/ericrav/theme-party
- Owner: ericrav
- License: mit
- Created: 2023-06-22T00:48:51.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-16T18:30:35.000Z (almost 2 years ago)
- Last Synced: 2024-09-16T22:56:12.860Z (almost 2 years ago)
- Topics: react, theme, typescript
- Language: TypeScript
- Homepage:
- Size: 107 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Theme Party
Theme Party is an unstyled & unopinionated method of providing an interchangeable theme to React apps.
You can structure your theme objects however you like, and use any styling engine. Themes can override primitive values (such as colors & fonts)
as well as swap out entire components for more complex layout differences between themes.
## Quick Start
Theme Party has the following major exports:
- `ThemeParty`
- `ThemeProvider`
- `useTheme`
- `costumed`
### Install
```
yarn add theme-party
```
### Make your first theme party
Create your first `ThemeParty` instance. This is generally where you should define the shape of your theme
and the types & names of design tokens/primitives you will use. This an example, you can use any shape or token names.
If you're using TypeScript, the instance will infer the type of your theme object.
```ts
import { ThemeParty } from 'theme-party';
export const myThemeParty = new ThemeParty({
color: {
primary: '#85FFC7',
secondary: '#297373',
accent: '#FF8552',
ghost: '#E6E6E6',
text: '#39393A',
link: theme => theme.color.primary,
},
spacing: {
sm: '4px',
md: '8px',
lg: '16px',
},
typography: {
sans: 'Arial',
serif: 'Georgia',
},
});
```
This instance can act as your default theme.
If you're using TypeScript, make your custom theme shape available to other `theme-party` utils by adding to the above:
```ts
declare module 'theme-party' {
interface UserTheme {
default: typeof myThemeParty;
}
}
```
### Create an alternate theme
Create another theme by extending your first with overrides.
```ts
const myOtherTheme = myThemeParty.createTheme({
color: {
primary: '#CE2D4F', // this will update both the primary color and the link color (since link points to primary)
secondary: theme => theme.color.accent,
},
});
```
### Add a theme provider to your React app
```tsx
import { ThemeProvider } from 'theme-party';
export function App() {
const [theme, setTheme] = useState(myThemeParty);
return (
// ...
setTheme(myOtherTheme)}>
Change theme
);
}
```
`ThemeProvider` takes a `ThemeParty` instance as its `theme` prop.
It can be nested further down in your component hierarchy to override the theme for its children.
### Use theme values in your components
Use the `useTheme` hook to retrieve your active theme's values.
This can be combined with any method of styling such as Emotion or Tailwind.
```tsx
import { useTheme } from 'theme-party';
export function Link({ children }) {
const theme = useTheme();
return (
{children}
);
}
```
### Replace components ("costuming")
Create a "costumed" component containing your default markup.
```tsx
import { costumed } from 'theme-party';
interface Props {
name: string;
}
export const MyComponent = costumed(function MyComponent({ name }) {
return
Hello, {name}
;
});
```
In your theme, replace the component with another by calling `useComponent` with the original costumed component above and a replacement component that matches the same props;
```tsx
myOtherTheme.useComponent(MyComponent, ({ name }) => (
));
```
Then render the original component anywhere in your app. If the active theme has its own version of the component, it will be rendered in its place.
```tsx
function Page() {
return (
);
}
```
### Theme overrides
Sometimes, you might want to override a single theme value, while inheriting the rest of the current theme.
```tsx
import { ThemeOverride, ThemePartyConfig } from 'theme-party';
const override: ThemePartyConfig = { color: { link: 'blue' } };
function Component() {
return (
Click me
);
}
```
This creates a temporary theme that preserves the rest of the values of the currently selected theme.
Note: the object passed to value must be stable across renders. Either use a constant or memoize the object.
## Contributing
### Releasing
In pull request branch, run
```
yarn version [patch|minor|major] --deferred
```
and commit yarn version file. When PR is merged, the package version will
be updated accordingly. See [Yarn Release Workflow](https://yarnpkg.com/features/release-workflow) for more details.