-
Notifications
You must be signed in to change notification settings - Fork 4.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(Shorthand|Theming): rework docs to be more actual (#3564)
* docs(Shorthand|Theming): rework docs to be more actual * remove extension
- Loading branch information
1 parent
c532f72
commit 3067f5a
Showing
10 changed files
with
359 additions
and
58 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| import { Header, Message } from 'semantic-ui-react' | ||
|
|
||
| export const meta = { | ||
| title: 'Augmentation', | ||
| } | ||
|
|
||
| <Header as='h1' content='Augmentation' textAlign='center' /> | ||
|
|
||
| React components are inherently composable. Semantic UI React makes them even more so with the `as` prop feature: you can control the rendered HTML tag, or render one component as another component. | ||
|
|
||
| ```jsx | ||
| <> | ||
| // will produce <button class='ui button' /> | ||
| <Button /> | ||
| // 🔨 will produce <a class='ui button' /> | ||
| <Button as='a' /> | ||
| </> | ||
| ``` | ||
|
|
||
| Augmentation is powerful. You can compose component features and props without adding extra nested components. This is essential for working with `MenuLink`s and `react-router`. | ||
|
|
||
| <Message info size='mini'> | ||
| Unhandled props by a component are passed to the component you are rendering <code>as</code>. | ||
| </Message> | ||
|
|
||
| ```jsx | ||
| import { Link } from 'react-router-dom' | ||
|
|
||
| ;<Menu> | ||
| // 💡 `to` does not belong to `Menu.Item` props and will be passed to `Link` | ||
| <Menu.Item as={Link} to='/home'> | ||
| Home | ||
| </Menu.Item> | ||
| </Menu> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| import { Header, Icon, Message } from 'semantic-ui-react' | ||
|
|
||
| export const meta = { | ||
| title: 'Shorthand Props', | ||
| } | ||
|
|
||
| <Header as='h1' content='Shorthand Props' textAlign='center' /> | ||
|
|
||
| It is quite common for Semantic UI React component to have "shorthands" which accept shorthand values. For example, `Button` component has an `icon` shorthand which value defines the icon that will be rendered. | ||
|
|
||
| ```jsx | ||
| <Button icon='like' /> | ||
| ``` | ||
|
|
||
| There are several forms of shorthand values that can be provided, but all of them share one common thing - each is eventually evaluated to React Element. Thus, you can think of shorthand values as a recipe to customize rendered React Element at corresponding shorthand. | ||
|
|
||
| ## Object as value | ||
|
|
||
| Each component's shorthand has associated default element type. For example, by default there is `<Icon />` element rendered for `Button`'s icon shorthand. It is possible to customize props of this default element by providing props object as shorthand value: | ||
|
|
||
| ```jsx | ||
| // 💡 'color' and 'name' will be used as <Icon /> element's props | ||
| <Button content='Like' icon={{ color: 'red', name: 'like' }} /> | ||
| ``` | ||
|
|
||
| ## String as value | ||
|
|
||
| There is even shorter way to define default element's props - by using a primitive value. In that case provided shorthand value will be taken as a value for "default prop" of this element. | ||
|
|
||
| This could be much easier seen with an example. Here, again, we have a `Button` element with its icon being defined with shorthand - where provided `string` value will be used as icon's `name`: | ||
|
|
||
| ```jsx | ||
| <> | ||
| <Button content='Like' icon='like' /> | ||
| // 💡 has identical effect to the previous one | ||
| <Button content='Like' icon={{ name: 'like' }} /> | ||
| </> | ||
| ``` | ||
|
|
||
| This works because name is the default prop of shorthand's `<Icon />` element. | ||
|
|
||
| ```jsx | ||
| <> | ||
| <Modal trigger={<Button>Show</Button>} content='Content' /> | ||
| // 💡 has identical effect to the previous one | ||
| <Modal trigger={<Button>Show</Button>} content={{ content: 'Content' }} /> | ||
| // ⛔ example below has broken styling, see section about React Element | ||
| <Modal trigger={<Button>Show</Button>} content={<div>Content</div>} /> | ||
| </> | ||
| ``` | ||
|
|
||
| ## Disable shorthand's rendering | ||
|
|
||
| It is also possible to pass falsy values (`false`, `null` or `undefined`) to shorthand prop - in that case there will be nothing rendered for the component's shorthand. | ||
|
|
||
| ```jsx | ||
| <Dropdown icon={null} /> | ||
| ``` | ||
|
|
||
| ## React Element as value | ||
|
|
||
| There are cases where it might be necessary to customize element tree that will be rendered as a shorthand's value. Returning to `Button` example, we might want to render `<i />` instead of default `<Icon />` element. In that case necessary element might be directly provided as shorthand value: | ||
|
|
||
| ```jsx | ||
| <Button icon={<i className='my-icon' />} /> | ||
| ``` | ||
|
|
||
| <Message icon size='small' warning> | ||
| <Icon name='warning' /> | ||
| <Message.Content> | ||
| There is a very important caveat here, though: whenever React Element is directly used as a | ||
| shorthand value, all props that Semantic UI React has created for the shorthand's Component will | ||
| be spread on the passed element. This means that provided element should be able to handle props | ||
| - while this requirement is satisfied for all SUIR components, you should be aware of that when | ||
| either HTML or any third-party elements are provided. | ||
| </Message.Content> | ||
| </Message> | ||
|
|
||
| Due to this limitation, you should strive to use other options for shorthand values whenever is possible - for instance, this is how previous example can be rewritten: | ||
|
|
||
| ```jsx | ||
| <Button icon={{ as: 'i', className: 'my-icon' }} /> | ||
| ``` | ||
|
|
||
| However, there still might be cases where it would be impossible to use object form of the shorthand value - for example, you might want to render some custom elements tree for the shorthand. In that case function value should be used. | ||
|
|
||
| ## Function as value | ||
|
|
||
| Providing function as a shorthand value is the most involving but, at the same time, the most powerful option for customizing component's shorthand. The only requirements for this function are: | ||
|
|
||
| - it should finish syncronously | ||
| - it should return React Element as a result | ||
|
|
||
| Thus, in its simplest form, it could be used the following way: | ||
|
|
||
| ```jsx | ||
| <Button | ||
| content='Like' | ||
| icon={(Component, componentProps) => <Component {...componentProps} color='red' name='like' />} | ||
| /> | ||
| ``` | ||
|
|
||
| ## Customizing rendered shorthand | ||
|
|
||
| There is another use case when render function is very useful for - this is the case where custom element's tree should be rendered for the shorthand. As you might recall, there is a problem that might happen when React Element is provided directly as shorthand value - in that case props are not propagated to rendered. In order to avoid that the following strategy should be considered: | ||
|
|
||
| ```jsx | ||
| <Button content='Like' icon={(Component, componentProps) => <Label basic>+1</Label>} /> | ||
| ``` |
Oops, something went wrong.