Skip to content
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

Jump to bottom

docs(variants): Clearly explain variant notation #1494

Merged
merged 2 commits into from Feb 15, 2021
Merged

docs(variants): Clearly explain variant notation #1494

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ec287e
docs(variants): Clearly explain variant notation
lachlanjc Feb 8, 2021
a786614
Add section about styles variants
lachlanjc Feb 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
25 changes: 20 additions & 5 deletions packages/docs/src/pages/guides/variants.mdx
View file
Open in desktop
Expand Up @@ -30,17 +30,20 @@ For example, you can define `primary` and `secondary` variants for buttons and u
}
```

With the `theme` object above, the `buttons` variants can be referenced by any tag through the `sx` prop.
With the `theme` object above, the `buttons` variants can be referenced by any tag through [the `sx` prop](/sx-prop).
Inside `sx`, the variant should begin with a top-level key from the theme, then use dot notation to access nested objects.

```jsx
<button sx={{ variant: 'buttons.primary' }} />
```

When using the [built-in components](/components), you can use the `variant` prop directly on components,
instead of inside the `sx` object.

Most [components have their own variant group](/components/variants)
(e.g. the [`Button` component](/components/button) uses `buttons`),
and some also have a default variant they’ll utilize from that variant group (e.g. `Button` uses `primary`).
(“variant group” being a top-level theme key, e.g. the [`Button` component](/components/button) uses `buttons`),
and some also have a default variant they’ll utilize from that variant group
(e.g. `Button` defaults to using `primary`).

This means using `<Button />` without specifying a variant has the same result as the snippet above,
since the default variant name (`primary`) matches a variant name inside the `buttons` group.
Expand All @@ -53,7 +56,7 @@ If you want a different variant from the same group, you can give its key withou
You can also use variants outside of a component’s default variant group with dot notation.
This is especially useful for combining layout components without further nesting your DOM,
such as adding container styles to a grid or flexbox. By using the [`Grid` component](/components/grid)
here, you’re still able to use `Grid`’s props, and the variant styles are combined with the grid’s.
here with a variant, you’re able to use `Grid`’s props combined with the variant styles.

```jsx
<Grid variant="layouts.container" columns={3} gap={3} />
Expand Down Expand Up @@ -162,7 +165,19 @@ These variants can then be used in the `theme.styles` object, with the `sx` prop
/>
```

## Themeable Layout Components
## `styles` variants

Variants inside the `styles` object, while usable through the same mechanisms as regular variants,
are also used for other Theme UI APIs.

- The entire [`styles` object](/theme-spec#styles) can style child HTML elements or MDX content,
Copy link
Member

Choose a reason for hiding this comment

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

Hey @lachlanjc, I'm not sure if this bullet doesn't "conflict" with the last one.
BaseStyles is used to style embedded HTML content, but MDX is styled with Themed (i.e. ## maps to Themed.h2)

Copy link
Member Author

Choose a reason for hiding this comment

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

Hmm. Using Next.js that's not the case (MDX is treated the same as HTML children, so you need BaseStyles), so I've never experienced that. I guess we can just remove the MDX reference for now?

Copy link
Member

@hasparus hasparus Feb 15, 2021 •
edited

Choose a reason for hiding this comment

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

MDX is treated the same as HTML children

That MDXProvider rendered by our ThemeProvider doesn't work in Next? (We pass an object with components through context)

Copy link
Member Author

Choose a reason for hiding this comment

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

Nope: #1130

Copy link
Member

Choose a reason for hiding this comment

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

Doesn't a new version of MDX packages specified in resolutions solve that issue?

#1130 (comment)

Copy link
Member Author

Choose a reason for hiding this comment

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

Perhaps! Forgot about that & have never tried it

Copy link
Member

Choose a reason for hiding this comment

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

I guess we can just remove the MDX reference for now?

Yeah, this sound like a good idea :D

Copy link
Member Author

Choose a reason for hiding this comment

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

fbb3451

via the [`BaseStyles` component](/api/#basestyles)
- If the [`useRootStyles` configuration option](/theming#configuration-flags) is enabled,
the `styles.root` object will style the `<body>` element
- [`Themed` components](/themed) will use their respective variant from inside `styles`,
e.g. `<Themed.h2>` uses `styles.h2`

## Themeable layout components

Variants can also be used to create themeable layout components.
This is especially useful when creating [Gatsby themes][],
Expand Down