|
|
|
@ -22,9 +22,11 @@ In effect, components allow you to write a JavaScript function that takes some d
|
|
|
|
|
|
|
|
|
|
> [!hint]
|
|
|
|
|
> For those coming from React, Quartz components are different from React components in that it only uses JSX for templating and layout. Hooks like `useEffect`, `useState`, etc. are not rendered.
|
|
|
|
|
|
|
|
|
|
## An Example Component
|
|
|
|
|
|
|
|
|
|
### Constructor
|
|
|
|
|
|
|
|
|
|
Component files are written in `.tsx` files that live in the `quartz/components` folder. These are re-exported in `quartz/components/index.ts` so you can use them in layouts and other components more easily.
|
|
|
|
|
|
|
|
|
|
Each component file should have a default export that satisfies the `QuartzComponentConstructor` function signature. It is a function that takes in a single optional parameter `opts` and returns a Quartz Component. The type of the parameters `ops` is defined by the interface `Options` which you as the component creator also decide.
|
|
|
|
@ -37,7 +39,7 @@ interface Options {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
const defaultOptions: Options = {
|
|
|
|
|
favouriteNumber: 42
|
|
|
|
|
favouriteNumber: 42,
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export default ((userOpts?: Options) => {
|
|
|
|
@ -55,6 +57,7 @@ export default ((userOpts?: Options) => {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Props
|
|
|
|
|
|
|
|
|
|
The Quartz component itself (lines 11-17 highlighted above) looks like a React component. It takes in properties (sometimes called [props](https://react.dev/learn/passing-props-to-a-component)) and returns JSX.
|
|
|
|
|
|
|
|
|
|
All Quartz components accept the same set of props which are defined in `QuartzComponentProps`:
|
|
|
|
@ -79,6 +82,7 @@ export type QuartzComponentProps = {
|
|
|
|
|
- `displayClass`: a utility class that indicates a preference from the user about how to render it in a mobile or desktop setting. Helpful if you want to conditionally hide a component on mobile or desktop.
|
|
|
|
|
|
|
|
|
|
### Styling
|
|
|
|
|
|
|
|
|
|
Quartz components can also define a `.css` property on the actual function component which will get picked up by Quartz. This is expected to be a CSS string which can either be inlined or imported from a `.scss` file.
|
|
|
|
|
|
|
|
|
|
Note that inlined styles **must** be plain vanilla CSS.
|
|
|
|
@ -116,15 +120,18 @@ export default (() => {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
> [!warning]
|
|
|
|
|
> Quartz does not use CSS modules so any styles you declare here apply *globally*. If you only want it to apply to your component, make sure you use specific class names and selectors.
|
|
|
|
|
> Quartz does not use CSS modules so any styles you declare here apply _globally_. If you only want it to apply to your component, make sure you use specific class names and selectors.
|
|
|
|
|
|
|
|
|
|
### Scripts and Interactivity
|
|
|
|
|
|
|
|
|
|
- listening for the nav event
|
|
|
|
|
- best practice: anything here should unmount any existing event handlers to prevent memory leaks
|
|
|
|
|
|
|
|
|
|
### Using a Component
|
|
|
|
|
#### In a layout
|
|
|
|
|
#### In the configuration
|
|
|
|
|
|
|
|
|
|
#### In a layout
|
|
|
|
|
|
|
|
|
|
#### In the configuration
|
|
|
|
|
|
|
|
|
|
> [!hint]
|
|
|
|
|
> Look in `quartz/components` for more examples of components in Quartz as reference for your own components!
|
|
|
|
|