Overview

Customization

Inner working

Style props

Dark or light mode

Flex

Group

Stack

Container

Center

Divider

Space

Textinput

NumberInput

Button

ButtonGroup

ActionIcon

Native Select

Title

Text

useForm

Appshell

Table

Table from data object

Paper

Accordion

Tabs

Dark Color Palette

Gray Color Palette

Bar Chart

Progress

Pagination

Default theme

Global Style: Colors

Global style: Others

# Overview

Mantine provides drop-in pre-styled components.

### overall benefits

-   solid, unremarkable, neutral, functional style (UI)
-   easy to use and consistent API (DX)
-   rapid development of utilitarian webapps

### default overall style

The default overall style is functional, neutral and minimalist..

### component variants

For some components, Mantine provides different variants. For example,
it provides _outline_ or _filled_ Button. This serves as distinct
appearances.

### component inner components

a component is constructed through several, named, inner components.
Slider example: a slider has a mark, a track and a bar.

### against transformative customization

Mantine provides a set of cohesive style options.

The risk of big style change is to lose the cohesive aspect. We must
ensure the custom style we bring is compatible with mantine default
styles.

If we are to replace all mantine default style, We don't need to keep it
cohesive with Mantine's design system. In this scenario, we use Mantine
as a headless, unstyled library.



# Customization

mantine allows extensive customization.

Common customization is convenient to set.

### customization through top level attributes

setting style through attributes is convenient.

As a trade-off, those options only target the root (top-level)
inner-component and have limited or no capability for customizing nested
inner-components.

For example, setting the _c_ prop on a _Slider_ in not precise enough to
target distinct inner components. It only affects the root inner
component.

### universal props or component specific props

Some props are shared by all components and may be applied on all of
them. They translate to inline style such as setting the margin or the
padding.

A component may have a set of props that are unique to this specific
component, or shared by a few components. For example, The _TextInput_
has a _label_ prop. Those props only make sense on a specific component
or on a specific kind of components. They may influence the style or
provide a functional aspect, such as providing the _label_ an input.

### customize the inner-components

We target some inner components explicitely, and provide, for each, some
inline style or a set of classes.

the _styles_ prop allows to target some inner components and to provide
for each some inline style.

the _classNames_ prop allows to target some inner components and provide
for each a set of classes.

### implement mantine-applied CSS classes

Mantine applies empty classes on each component and its inner
components. We may implement such classes to style either the root
component or inner components.

For example, `mantine-Button-root` is applied on a Button's root,
while _<u>mantine-Button-loader</u>_ is applied on a Button's loader,
when the button is in the loading state, and
_<u>mantine-Button-label</u>_ is applied on the text node we provide
inline within the button.

The empty classes have by default the same priority as Mantine's own
implemented classes. To give more priority to the classes we implement,
we must implement them in a stylesheet with higher priority. That is, we
import our stylesheet after Mantine's.

This technique effectively mutates the Mantine component globally.

provide style at component use site

### customize a single component with inline style scoped to inner components.

We may provide inline style with subcomponent granularity. We provide
the inline style inside a styles prop.

This requires knowing the inner components.

For each subcomponent, we provide a styling JSX object.

In the styling JS object: the property name (such as
_<u>backgroundColor</u>_) matches the CSS property (background-color)
but through camelCase. the CSS value is provided as-is, within quotes or
not.

The inline style is limited because it cannot target the instance in a
specific state such as hover.

```tsx
 <Button
	styles={{
        root: { backgroundColor: 'red', height: 16},
        label: { color: 'blue' },
        inner: { fontSize: 20 },
      }}
```

### customize a single component with classes scoped to inner components.

We attach style to a class, and then put that class on a component or a
subcomponent.

The benefit is the ability to specify state-specific style, such as
hover specific style, and still be able to target a subcomponents.

```css
.button_root {
}
.button_root:hover {
}
.button_root:active {
}
.button_label {
}
```

```tsx
<Button
    classNames={{
        root: "button_root",
        label: "button_label",
    }}
/>
```

### inner component name to class name, one-to-one matching.

we may use a tool to remove the risk of class name collision. Through
that tool, we can target the inner component name directly

```css
.root {
}
.root:hover {
}
label {
}
```

```tsx
import classNames from ""
;<Button classNames={classNames} />
```

### helper for writing classes for component and subcomponents.

target dark or light mode

sourcecode

[<u>https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components</u>](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components)



# Inner working

What happens when we use a Mantine's \<Button\>

sourcecode (unbuilt):

[<u>https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components/Button</u>](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components/Button)

### html element tree

the innermost span contains only text

the intermediate _inner_ span contain icons and the innermost span

the root contains the _inner_ span, and may probably replace it on
loading state.

```pug
button
	span
		span
		BUTTON_TEXT
		/span
	/span
/button
```

terminology and empty classes

```pug
root // mantine-Button-root
	inner // mantine-Button-inner
		label // mantine-Button-label
			text
		lbael
	inner
root
```

mantine private use classes and empty classes

```tsx
<button class="m-77c9d27d mantine-Button-root .." type="button">
    {" "}
    // root
    <span class="m-80f1301b mantine-Button-inner">
        {" "}
        // inner
        <span class="m-811560b9 mantine-Button-label"> // label Save</span>
    </span>
</button>
```

### class analysis

classes on the top level inner-component, which happens to be the
\<button\> element.

```pug
m-87cf2631				// Mantine implemented class, (UnstyledButton)
m-77c9d27d				// Mantine implemented class, (Button)

mantine-UnstyledButton-root	// empty class, allows customization
mantine-Button-root		// empty class, allows customization

mantine-active			// allows :active
mantine-focus-auto		// allows :focus-visible
```

### mantine implemented class for Button's root:

the designed implementation for the top-level inner component, aka
_root_. (not shipped, unprocessed):

```css
.root {
    --button-height-xs: rem(30px);
    --button-height-sm: rem(36px);
    --button-height-md: rem(42px);
    --button-height-lg: rem(50px);
    --button-height-xl: rem(60px);

    --button-height-compact-xs: rem(22px);
    --button-height-compact-sm: rem(26px);
    --button-height-compact-md: rem(30px);
    --button-height-compact-lg: rem(34px);
    --button-height-compact-xl: rem(40px);

    --button-padding-x-xs: rem(14px);
    --button-padding-x-sm: rem(18px);
    --button-padding-x-md: rem(22px);
    --button-padding-x-lg: rem(26px);
    --button-padding-x-xl: rem(32px);

    --button-padding-x-compact-xs: rem(7px);
    --button-padding-x-compact-sm: rem(8px);
    --button-padding-x-compact-md: rem(10px);
    --button-padding-x-compact-lg: rem(12px);
    --button-padding-x-compact-xl: rem(14px);

    --button-height: var(--button-height-sm);
    --button-padding-x: var(--button-padding-x-sm);
    --button-color: var(--mantine-color-white);

    user-select: none;
    font-weight: 600;
    position: relative;
    line-height: 1;
    text-align: center;
    overflow: hidden;

    width: auto;
    cursor: pointer;
    display: inline-block;
    border-radius: var(--button-radius, var(--mantine-radius-default));
    font-size: var(--button-fz, var(--mantine-font-size-sm));
    background: var(--button-bg, var(--mantine-primary-color-filled));
    border: var(--button-bd, rem(1px) solid transparent);
    color: var(--button-color, var(--mantine-color-white));
    height: var(--button-height, var(--button-height-sm));
    padding-inline: var(--button-padding-x, var(--button-padding-x-sm));
    vertical-align: middle;

    &:where([data-block]) {
        display: block;
        width: 100%;
    }

    &:where([data-with-left-section]) {
        padding-inline-start: calc(var(--button-padding-x) / 1.5);
    }

    &:where([data-with-right-section]) {
        padding-inline-end: calc(var(--button-padding-x) / 1.5);
    }

    &:where(:disabled:not([data-loading]), [data-disabled]:not([data-loading])) {
        cursor: not-allowed;
        border: rem(1px) solid transparent;
        transform: none;

        @mixin where-light {
            color: var(--mantine-color-gray-5);
            background: var(--mantine-color-gray-1);
        }

        @mixin where-dark {
            color: var(--mantine-color-dark-3);
            background: var(--mantine-color-dark-6);
        }
    }

    &::before {
        content: "";
        pointer-events: none;
        position: absolute;
        inset: rem(-1px);
        border-radius: var(--button-radius, var(--mantine-radius-default));
        transform: translateY(-100%);
        opacity: 0;
        filter: blur(12px);
        transition: transform 150ms ease, opacity 100ms ease;

        @mixin where-light {
            background-color: rgba(255, 255, 255, 0.15);
        }

        @mixin where-dark {
            background-color: rgba(0, 0, 0, 0.15);
        }
    }

    &:where([data-loading]) {
        cursor: not-allowed;
        transform: none;

        &::before {
            transform: translateY(0);
            opacity: 1;
        }

        & .inner {
            opacity: 0;
            transform: translateY(100%);
        }
    }

    @mixin hover {
        &:where(:not([data-loading], :disabled, [data-disabled])) {
            background-color: var(--button-hover, var(--mantine-primary-color-filled-hover));
            color: var(--button-hover-color, var(--button-color));
        }
    }
}
```

the actuall shipped class (before refactor to where)

```css
.m-77c9d27d {
    --button-height-xs: calc(1.875rem * var(--mantine-scale));
    --button-height-sm: calc(2.25rem * var(--mantine-scale));
    --button-height-md: calc(2.625rem * var(--mantine-scale));
    --button-height-lg: calc(3.125rem * var(--mantine-scale));
    --button-height-xl: calc(3.75rem * var(--mantine-scale));
    --button-height-compact-xs: calc(1.375rem * var(--mantine-scale));
    --button-height-compact-sm: calc(1.625rem * var(--mantine-scale));
    --button-height-compact-md: calc(1.875rem * var(--mantine-scale));
    --button-height-compact-lg: calc(2.125rem * var(--mantine-scale));
    --button-height-compact-xl: calc(2.5rem * var(--mantine-scale));
    --button-padding-x-xs: calc(0.875rem * var(--mantine-scale));
    --button-padding-x-sm: calc(1.125rem * var(--mantine-scale));
    --button-padding-x-md: calc(1.375rem * var(--mantine-scale));
    --button-padding-x-lg: calc(1.625rem * var(--mantine-scale));
    --button-padding-x-xl: calc(2rem * var(--mantine-scale));
    --button-padding-x-compact-xs: calc(0.4375rem * var(--mantine-scale));
    --button-padding-x-compact-sm: calc(0.5rem * var(--mantine-scale));
    --button-padding-x-compact-md: calc(0.625rem * var(--mantine-scale));
    --button-padding-x-compact-lg: calc(0.75rem * var(--mantine-scale));
    --button-padding-x-compact-xl: calc(0.875rem * var(--mantine-scale));
    --button-height: var(--button-height-sm);
    --button-padding-x: var(--button-padding-x-sm);
    --button-color: var(--mantine-color-white);
    background: var(--_button-bg, var(--button-bg, var(--mantine-primary-color-filled)));
    border: var(
        --_button-bd,
        var(--button-bd, calc(0.0625rem * var(--mantine-scale)) solid transparent)
    );
    border-radius: var(--button-radius, var(--mantine-radius-default));
    color: var(--_button-color, var(--button-color, var(--mantine-color-white)));
    cursor: var(--_button-cursor, pointer);
    display: var(--_button-display, inline-block);
    font-size: var(--button-fz, var(--mantine-font-size-sm));
    font-weight: 600;
    height: var(--button-height, var(--button-height-sm));
    line-height: 1;
    overflow: hidden;
    padding-left: var(--_button-padding-left, var(--button-padding-x, var(--button-padding-x-sm)));
    padding-right: var(
        --_button-padding-right,
        var(--button-padding-x, var(--button-padding-x-sm))
    );
    position: relative;
    text-align: center;
    user-select: none;
    width: var(--_button-width, auto);
}

.m-77c9d27d[data-block] {
    --_button-display: block;
    --_button-width: 100%;
}
.m-77c9d27d[data-with-left-section] {
    --_button-padding-left: calc(var(--button-padding-x) / 1.5);
}
[dir="rtl"] .m-77c9d27d[data-with-left-section] {
    --_button-padding-left: var(--button-padding-x);
}
.m-77c9d27d[data-with-right-section],
[dir="rtl"] .m-77c9d27d[data-with-left-section] {
    --_button-padding-right: calc(var(--button-padding-x) / 1.5);
}
[dir="rtl"] .m-77c9d27d[data-with-right-section] {
    --_button-padding-right: var(--button-padding-x);
    --_button-padding-left: calc(var(--button-padding-x) / 1.5);
}
.m-77c9d27d:disabled:not([data-loading]),
.m-77c9d27d[data-disabled]:not([data-loading]) {
    --_button-cursor: not-allowed;
    --_button-bg: var(--_disabled-bg);
    --_button-color: var(--_disabled-color);
    --_button-bd: calc(0.0625rem * var(--mantine-scale)) solid transparent;
    transform: none;
}

.m-77c9d27d:before {
    background-color: var(--_button-loading-overlay-bg);
    border-radius: var(--button-radius, var(--mantine-radius-default));
    content: "";
    filter: blur(12px);
    inset: calc(-0.0625rem * var(--mantine-scale));
    opacity: 0;
    pointer-events: none;
    position: absolute;
    transform: translateY(-100%);
    transition: transform 0.15s ease, opacity 0.1s ease;
}
.m-77c9d27d[data-loading] {
    --_button-cursor: not-allowed;
    transform: none;
}
.m-77c9d27d[data-loading]:before {
    opacity: 1;
    transform: translateY(0);
}
.m-77c9d27d[data-loading] .m-80f1301b {
    opacity: 0;
    transform: translateY(100%);
}
.m-77c9d27d[data-loading] .m-a25b86ee {
    opacity: 1;
    transform: translate(-50%, -50%);
}
@media (hover: hover) {
    .m-77c9d27d:hover:not([data-loading]):not(:disabled):not([data-disabled]) {
        --_button-bg: var(--button-hover, var(--mantine-primary-color-filled-hover));
        --_button-color: var(--button-hover-color);
    }
}
@media (hover: none) {
    .m-77c9d27d:active:not([data-loading]):not(:disabled):not([data-disabled]) {
        --_button-bg: var(--button-hover, var(--mantine-primary-color-filled-hover));
        --_button-color: var(--button-hover-color);
    }
}
[data-mantine-color-scheme="light"] .m-77c9d27d {
    --_disabled-color: var(--mantine-color-gray-5);
    --_disabled-bg: var(--mantine-color-gray-1);
    --_button-loading-overlay-bg: hsla(0, 0%, 100%, 0.15);
}
[data-mantine-color-scheme="dark"] .m-77c9d27d {
    --_disabled-color: var(--mantine-color-dark-3);
    --_disabled-bg: var(--mantine-color-dark-6);
    --_button-loading-overlay-bg: rgba(0, 0, 0, 0.15);
}
```



# Style props

| Prop        | CSS Property              | Theme key                                     |
| ----------- | ------------------------- | --------------------------------------------- |
| **m**       | margin                    | theme.spacing                                 |
| **mt**      | marginTop                 | theme.spacing                                 |
| **mb**      | marginBottom              | theme.spacing                                 |
| **ml**      | marginLeft                | theme.spacing                                 |
| **mr**      | marginRight               | theme.spacing                                 |
| **mx**      | marginRight, marginLeft   | theme.spacing                                 |
| **my**      | marginTop, marginBottom   | theme.spacing                                 |
|             |                           |                                               |
| **p**       | padding                   | theme.spacing                                 |
| **pt**      | paddingTop                | theme.spacing                                 |
| **pb**      | paddingBottom             | theme.spacing                                 |
| **pl**      | paddingLeft               | theme.spacing                                 |
| **pr**      | paddingRight              | theme.spacing                                 |
| **px**      | paddingRight, paddingLeft | theme.spacing                                 |
| **py**      | paddingTop, paddingBottom | theme.spacing                                 |
|             |                           |                                               |
| **bg**      | background                | theme.colors                                  |
| bgsz        | backgroundSize            | –                                             |
| bgp         | backgroundPosition        | –                                             |
| bgr         | backgroundRepeat          | –                                             |
| bga         | backgroundAttachment      | –                                             |
|             |                           |                                               |
| **c**       | color                     | theme.colors gray.5 blue blue.7 blue.5 blue.0 |
| **opacity** | opacity                   | –                                             |
|             |                           |                                               |
| **ff**      | fontFamily                | –                                             |
| **fz**      | fontSize                  | theme.fontSizes                               |
| **fw**      | fontWeight                | –                                             |
| **lts**     | letterSpacing             | –                                             |
| **ta**      | textAlign                 | –                                             |
| **lh**      | lineHeight                | theme.lineHeights                             |
| **fs**      | fontStyle                 | –                                             |
| **tt**      | textTransform             | –                                             |
| **td**      | textDecoration            | –                                             |
|             |                           |                                               |
| **w**       | width                     | theme.spacing                                 |
| **miw**     | minWidth                  | theme.spacing                                 |
| **maw**     | maxWidth                  | theme.spacing                                 |
| **h**       | height                    | theme.spacing                                 |
| **mih**     | minHeight                 | theme.spacing                                 |
| **mah**     | maxHeight                 | theme.spacing                                 |
|             |                           |                                               |
| **bgsz**    | backgroundSize            | –                                             |
| **bgp**     | backgroundPosition        | –                                             |
| **bgr**     | backgroundRepeat          | –                                             |
| **bga**     | backgroundAttachment      | –                                             |
|             |                           |                                               |
| **pos**     | position                  | –                                             |
| **top**     | top                       | –                                             |
| **left**    | left                      | –                                             |
| **bottom**  | bottom                    | –                                             |
| **right**   | right                     | –                                             |
| **inset**   | inset                     | –                                             |
|             |                           |                                               |
| **display** | display                   | –                                             |
|             |                           |                                               |
| flex        | flex                      |                                               |



# Dark or light mode

```tsx
<MantineProvider defaultColorScheme="dark"></MantineProvider>
```



# Flex

Thin abstraction over a flex div..

Mantine only sets the div to display:flex if no props are provided.

props:

-   the `direction`, horizontal by default. We often set vertical as a base
    for mobile, and switch back to horizontal on desktop. To match the
    flex's terminology: horizontal is _row_, while vertical is _column._
-   the `gap`, defaults to 0, due to matching regular flex.
-   the `justify`, main axis alignment. Default to _flex-start_, due to
    matching regular flex.
-   the `align`, cross-axis alignment. Defaults to _stretch_, due to matching
    regular flex.

### allow an attribute to pick a different value depending on screen size.

Instead of a single value, we provide an object with properties, most of
the time only two properties.

-   The base property provides the mobile value. All iPhones are under 450p
    in width. All non-plus size iPhones are under 400p
-   The xs or sm property provides the value for bigger devices, similar
    to a min-width media query, which applies to either 576p (36em) aka phablets and higher or 768px (48em) aka tablets and higher. iPad
    tablets start at 768px. When setting the breakpoint at sm size, we
    allow the iPads to benefit from the desktop style.

```tsx
<Flex
 direction=	{{ base: 'column',sm: 'row' }}
 gap=		{{ base: 'sm', 	sm: 'lg' }}
 justify=	{{ base: 'sm', 	sm: 'lg' }}
>
```



# Group

Layout elements horizontally, add some space between them. This is a
high-level abstraction over an horizontal flex. The container spans the whole line.

-   `gap`: defaults to some spacing, as opposed to a regular flex. The default
    spacing is _md_, aka 16px.
-   `justify`: defaults to flex-start. (elements sit at the left)
-   `align`: defaults to _center_ (vertically center), instead of _stretch_
    for regular flex.
-   `grow`: make all children have the same width. It first calculate the
    tentative equal width by dividing the remaining space by the number of
    items. It uses this tentative equal width a max-width for each children.
    Then, it sets flex-grow: 1 on each of them. If there was no limit, the
    bigger items would still be be bigger than the other even after the
    growing process, because each child would receive an equal share of the
    remaining space. Defaults to false. Also activates mono-line.
-   `wrap`: pick between mono-line or multi-line flex. Default to multi-line,
    probably to make it mobile "friendly", by preventing content clipping
    out of screen.

The subtle differences with a regular flex may not be worth it. The main draw could be the use of `grow` to make children of equal width.



# Stack

Layout elements vertically, add some space between elements.

A thin abstraction over a flex: by default, it only adds a gap and makes the flex vertical. The container spans the whole line.

-   `gap`: defaults to _16px_.
-   `justify`: defaults to browser's default: _flex-start_ (elements sit at
    the top),
-   `align`: defaults to browser's default: _stretch_ (stretch elements along the cross axis, spreading the whole width)

Like any div with the default _display:block_, the stack itself occupies
the full width.



# Container

Act as top level wrapper so that the inner content, such as the main column of a website, displays nicely, both in desktop and mobile.

In desktop, it would centers its content and limit its width. In mobile, it ensures minimum padding.

### limited width container

It claims a minimum padding, limits its own width and centers itself
through margins.

`size`: The max-width. Defaults to _md_ (aka 960px, 60rem). We may pick
720px instead by setting _sm_. If we are to provide an arbitrary numeric
value, we may use _maw_ directly for less indirection.

The default padding is 16px, aka _md_. We may set it with `px`.

### fluid container

We may opt for a fluid container: the container spreads to
occupy the whole width of its parent. It still brings some padding.
For that, we add `fluid` or set _size_ to 100%.

This is overkill because we may use a div with some padding instead.



# Center

A utility component that "CenterCenters" the child or children.

In effect it is by default a div with display:flex, set with:

-   justify-content: center
-   align-items: center

### vertical-centering and height.

To activate vertical centering of the inner content, we must set the
Center's height as bigger than the inner content.

### width of the center element

As a regular div, it occupies the whole parent's width unless limited in
width. It does not center itself, (that would be container) only it's
inner content.



# Divider

A line that acts as a separator/divider.

Similar to the \<hr\> element in usage, at least for the horizontal
version.

May be used as a horizontal line or a vertical line/divider.

Technically, Mantine uses an empty element whose border acts as the
visible line. The _size_ determines the line's size.

The line's default color is?

The line does not have any margin by default, we use _my_ or _mx_, or
set the spacing at the parent level.

-   `orientation`: set the line orientation, "horizontal" (default), or
    "vertical".
-   `size`: set the line thickness, _xs_ by default, aka 1px.
-   `variant`: set a line variant: solid (default), dashed or dotted



# Space

Add some space at a location in the layout. Abstraction over a div on
which we set some size. It defaults to size 0.

-   `h`, set the height, to set the vertical space, usually in a stack-like
    layout.
-   `w`, set the width, to set the horizontal space, usually in a horizontal
    flex-like layout.



# Textinput

It comprises:

-   the text input proper
-   the main label
-   a secondary label (optional)
-   an icon, visually inside the text input (optional)
-   some placeholder text (optional)

A text input has almost always a label that explains what this input is about.



# NumberInput

Under the hood, It's a text input. This allows more flexibility, such as displaying formatting commas directly in the input.

The value we get is a number or, when it's not possible to infer a number, a string. For example, we get an empty string when the input is empty.

We may customize the input:

-   `allowDecimal`: allow or forbid decimal numbers. Defaults to allow.
-   `allowNegative`: allow or forbid negative numbers. Defaults to allow.
-   `min`, `max`: specify minimum and maximum values. The way it influences the input is determined by `clampBehavior`
-   `clampBehavior`: determine how the value should clamp within the limits. We may forbid input outside the limits (`strict`), clamp after input on `blur` (d), or never clamp (`none`)

As any text input we may have:

-   `label`
-   `description` (secondary label)
-   `placeholder`

```tsx
const [value, setValue] = useState<string | number>("")
return <NumberInput value={value} onChange={setValue} />
```



# Button

An abstraction over a \<button\>.

### props

-   `variant`, set the button overall appearance, such as _filled_, _outline_,
    _subtle_, _gradient_ or _default_. defaults to _filled_
-   `color`, set the button overall color. the coloring depends on the
    variant. defaults to the theme's _primaryColor_, aka Mantine's blue.
-   `leftSection`, `rightSection`, for example for an icon.
-   `size`, to specify two things. First, if it's a _compact_ button with less
    inner space. second, if we want a smaller or bigger font size.
-   `fullWidth`, to fill the parent's width
-   `disabled`, sets the appearance and behaviour to disabled. the disabled
    appearance is the same across all variants.
-   `loading`, sets the appearance to loading, aka loader overlaid on top, and
    the behaviour to disabled. We may customize the loader with loaderProps
    (see Loader component)
-   `gradient`, sets the gradient's colors and direction. It requires using
    the _gradient_ variant.

```tsx
<Button rightSection={<IconDownload size={14} />}>Download</Button>
```

### Button not submitting form by default

Mantine adds _type=button_ on the underlying \<button\>. It prevents the
button from triggering the form submit, when pressed inside a \<form\>.

The idea is for the developper to explicitely set _type=submit_ on the
Button if it is set to submit the form.

### providing an onClick handler

The handler specifies which action to perform on click. This action
usually does not depend on any information related to the click event.

Still, the handler receives the event as an argument. If we define the
handler somewhere else than inline, we must indicate its typing. The
argument it takes is of type Event.

More specifically, the event is of type
_React.MouseEvent\<HTMLButtonElement \>_.

The _HTMLButtonElement_ type parameter indicates the type of the
_target_ of the event, which in this case is a \<button\> element.

The handler is not supposed to return anything.

Handler type signature

```tsx
onClick: React.MouseEvent<HTMLButtonElement> => void
```

shortcut type

```tsx
onClick: React.MouseEventHandler<HTMLButtonElement>
```



# ButtonGroup

We creates a button cluster/group, where the children buttons are
glued-up

We may use _ButtonGroup_ or _Button.Group_

```tsx
<ButtonGroup>
    <Button variant="default">First</Button>
    <Button variant="default">Second</Button>
    <Button variant="default">Third</Button>
</ButtonGroup>
```

we may set the orientation property to vertical if needed.



# ActionIcon

[<u>https://mantine.dev/core/action-icon/</u>](https://mantine.dev/core/action-icon/)

### icon button

ActionIcon serves the "icon as a button" pattern. UI-wise, the idea is
that the icon is expressive enough to be self-explanatory, with no need
for accompanying text, for example the "trash" icon refers to the
"delete" action.

Technically it is a container that is distinct from the icon, that must
be added as a child.

It gives its child icon the behaviour of a button, and it customizes its
appearance according to the selected variant.

-   `variant`: same variants as Button's variants. To get a naked icon effect,
    we select _subtle_ or _transparent_.
-   `size`: the container's size impacts the hover and active zone, and the
    icon scale.

### required child icon

As a wrapper, it impacts the concrete child icon.

We may still set _size_ directly on the child Icon.

```tsx
<ActionIcon variant='default'>
	<IconMail size={14} stroke={..?}/>
</ActionIcon>
```



# Native Select

[<u>https://mantine.dev/core/native-select/</u>](https://mantine.dev/core/native-select/)

An abstraction over an HTML _select_ element embedding some _option_
elements. Here, we do not nest actual _option_ elements. Instead, we
provide their data the in the _data_ attribute. For each option, we
provide the _label_ and the _value_.

If the _label_ is the same as the _value_ (not recommended), we may
provide a single string for each option, which act as both _label_ and
_value_.

-   `data`: an array of {label,value} elements.
-   `label`: The label that describes the select

```tsx
const options = [
    { label: "Death Knight", value: "death_knight" },
    { label: "Demon Hunter", value: "demon_hunter" },
]

const options = ["death_knight", "demon_hunter"]
```

```tsx
<NativeSelect label="Class" data={options} />
```



# Title

Abstraction over a heading element.

It strips away the default margin. The developer handles spacing either
through an explicit margin, or through other mechanisms.

The font's size and weight, along with the line height, come for
_theme.headings_. We have consistent headings accros the app by default.

All headings come in bold aka _fontWeight:700_.

their size vary from 16px to 34px

-   h5 comes at 16px
-   h4 comes at 18px
-   h3 comes at 22px
-   h2 comes at 26px
-   h1 comes at 34px

The fontSize matches the _order_ by default, so that there is some
hierarchy between headings. We may set a _size_ explicitely.

-   `order`: pick the underlying html element, such as _1_ to pick h1. _order_
    should always be specified, otherwise it defaults to h1, which should be
    unique. Affects the font-size
-   `size`: override the font-size caused by _order_. we pick a size in the
    heading hierarchy such as _h3_, or a number. Picking a size in the
    hierarchy creates indirection as the concrete value is not apparent.
-   `lineClamp`, sets the maximum number of lines. truncates the title with
    _text-overflow: ellipsis_, and with _-webkit-line-clamp: n_

For example, we indicate a h3 with a theme's h5 size.

```tsx
<Title order={3} size={"h5"}>
    Daybreak
</Title>
```



# Text

An abstraction over a paragraph element, with margins removed.

It does not change the Mantine's default 1.55 line height.

We may limit the number of lines.



# Box

Utility component that translates to an HTML element, by default div, on
which we may apply style.



# useForm

Gather data from user and send it to a server. Send it as-is or after
some (client-side) validation and/or transformation.

In React, a form uses either controlled or uncontrolled inputs. Mantine
provides both options.

The Mantine's _useForm_ hook attempts to provide a convenient way to
specify initial data, and specify validation and/or transformation to
perform on submit.

### Overview

We work with a regular \<form\>, a set of inputs, and a submit button.

We provide initial data in an object (_initialValues_). The user may
edit data through the inputs.

On submit, Mantine collects the data and provide it to the validator
and/or transformer. Then, it provides the processed data to the
callback, in principle for it to send it to the server.

When an initial value has no matching input (invisible, uneditable
property), Mantine still collects it.

### main steps

-   we create a _configuration_ object
-   We compute a configured _form_ object, through
    _useForm_(_configuration_)
-   We generate the form-submit handler with _form.onSubmit(f)_, where f is
    our callback to handle the processed data. The form-submit handler takes
    an event as argument, and is assigned to the \<form\> _onSubmit_
    attribute, which is the react version of standard _onsubmit_.
-   We add attributes to the form inputs so that they interoperate. we
    spread _form.getInputProps(email)_ to add the relevant attributes on the
    input, depending if it is controlled or uncontrolled: _value_ if it is
    controlled, _initialValue_ and _ref_ if it is uncontrolled. They also
    get _onChange_ and _onBlur_.

init form

```tsx
const form = useForm({ // config
  	initialValues: {x: "", y: ""},
	validate: f
	transformValues: (collected) => processed
})
```

form callback

```tsx
function my_callback(data) {
    data.x
    data.y
}

const mantineEventHandler = form.onSubmit(my_callback)
```

wire up

```tsx
form onSubmit={e => mantineEventHandler(e)}
	TextInput label="x" {...form.getInputProps('x')}
	TextInput label="x" {...form.getInputProps('y')}
	TextInput label="x" {...form.getInputProps('z') // z is not part of initial values, but may still be included if input is changed}
/form
```

### initial value or not.

Mantine collect properties from the initial values, even if there is no
matching input, and even if the value is null or undefined, and provide
them for processing.

If an input is connected to an initial value that does not exist, it is
effectively initialized to undefined, which will generate a React
warning. Mantine will collect the value of that input and associate with
the key provided in form.getInputProps??

### initial value for a TextInput

The initial value for a TextInput should no be null: it triggers a React
warning. It should also not be set to undefined. Instead, we should
initialize to empty string. We may do post-processing in the transformer
to change the empty string to null.

### utils

```tsx
// get current form values
form.values

// Set all or some form values
form.setValues(values)

// Set all form values using the previous state
form.setValues((prev) => ({ ...prev, ...values }))

// Set value of single field
form.setFieldValue("path", value)

// Set value of nested field
form.setFieldValue("user.firstName", "Jane")

// Resets form.values to initialValues,
// clears all validation errors,
// resets touched and dirty state
form.reset()

// Sets initial values, used when form is reset
form.setInitialValues({ values: "object" })
```



# Appshell

### overview

-   manages the banner (header)
-   manages the sidebar
-   embeds the main section

header (banner)

### Appshell.Header

The app's banner that stands ontop.

-   manages the burger button.
-   manages the logo.
-   manages the dark/light mode toggle

### header config

_header_ is a prop of AppShell

\- height

```tsx
header={{ height: 70 }}
```

navbar

### Appshell.Navbar

manages the left-side navbar

-   the navbar is hidden by default on mobile. When it is open, it takes the full width.
-   we open and close it by toggling _collapsed_ (to false or true). We
    track the state in a variable such as _opened_ and give it to
    _collapsed_. The burger button, should toggle _opened_ to true.
-   in desktop, it's better to always show up the navbar. By default, the navbar always shows up: it ignores the _opened_ variable given in _collapsed_, because we scoped it to _mobile._ _breakpoint_ determines
    when it goes into desktop mode. _width_ determines its desktop width.
-   we can create a distinct state variable to track the open state in
    desktop, or the use same as the mobile and provide it in _collapsed_, to the _desktop_ key.

### navbar config

_navbar_ is a prop of AppShell

-   width
-   breakpoint: from what size onward should we display the navbar
    unconditionally, aka activate desktop mode. For example, _sm_, which
    includes desktop mode for tablets. (see meaning of _sm_ for breakpoint
    later)
-   collapsed, for mobile (can also work for desktop),

```tsx
navbar={{ width: 300, breakpoint: 'sm', collapsed: { mobile: !opened } }}
```

### Appshell.Section: implement top and bottom sections

```tsx
<AppShell.Navbar>
    <AppShell.Section grow> </AppShell.Section>
    <AppShell.Section> </AppShell.Section>
</AppShell.Navbar>
```

main

### Appshell.Main

The container for the main panel. It's appropriate to set the main
panel's background color here.

For light mode, the background is white.

We may pick a light gray such as _gray.1_, to allow white Papers to
standout.

For dark mode, the background is dark.7???

```tsx
<AppShell.Main bg={colorScheme === "dark" ? "dark.8" : "gray.1"}>{children}</AppShell.Main>
```

Usage

### Configure subcomponents at Appshell level

the configuration object is required for each subcomponent.

```tsx
<AppShell
      header={{ .. }}
      navbar={{ .. }}
      padding="md"
>..subcomponents..</AppShell>
```

### Subcomponents, as children

```tsx
AppShell.Header
AppShell.Navbar
AppShell.Main
```

### Other involved components

```tsx
Burger
useDisclosure (@mantine/hooks')
```



# Table

### Abstract

A table is supposed to work with an array of items

    an array			<=> a table
    an item			<=> a row
    an item's property	<=> a cell

example data

```tsx
;[
    { position: 6, mass: 12.011, symbol: "C", name: "Carbon" },
    { position: 7, mass: 14.007, symbol: "N", name: "Nitrogen" },
    { position: 39, mass: 88.906, symbol: "Y", name: "Yttrium" },
    { position: 56, mass: 137.33, symbol: "Ba", name: "Barium" },
    { position: 58, mass: 140.12, symbol: "Ce", name: "Cerium" },
]
```

### Overall structure

```tsx
Table
	Table.Thead
		Table.Tr
			Table.Th
			Table.Th
			Table.Th
	Table.Tbody
		Table.Tr
			Table.Td
			Table.Td
			Table.Td
		Table.Tr
			Table.Td
			Table.Td
			Table.Td
		...
```

### the table head contains labels

Thead contains labels.. A _th_ defines the label for that column.

### the table body contains data, a row represents a record.

Tr represents a record. Each value is displayed in a distinct Td cell.

### Regular rows

Fill the cell out of a property

```tsx
<Table.Td>{record.name}</Table.Td>
```

Create a row out of an element, as the container of cells

```tsx
;(record) => (
    <Table.Tr>
        <Table.Td>{record.name}</Table.Td>
        <Table.Td>{record.level}</Table.Td>
        <Table.Td>{record.class}</Table.Td>
    </Table.Tr>
)
```

Create a row list out of an element list, store it in _rows_

```tsx
const rows = records.map((record) => (
    <Table.Tr>
        <Table.Td>{record.name}</Table.Td>
        <Table.Td>{record.level}</Table.Td>
        <Table.Td>{record.class}</Table.Td>
    </Table.Tr>
))
```

the Tbody is the container for the regulars rows. We provide the _rows_

```tsx
<Table.Tbody>{rows}</Table.Tbody>
```

### Header row

```tsx
a single label 	<=> a cell
all labels		<=> a row
```

The Thead is the container for the header row.

```tsx
<Table.Thead>
    <Table.Tr>
        <Table.Th>{label1}</Table.Th>
        <Table.Th>{label2}</Table.Th>
        <Table.Th>{label3}</Table.Th>
    </Table.Tr>
</Table.Thead>
```



# Table from data object

Provide complete table data as an object, containing some arrays:

-   Array of labels for the head
-   Array of elements for the body.
-   We cannot provide elements as objects as the properties ordering is
    unclear. We instead provides the elements as arrays of properties, so that each property has a clear order. For the table body, the cell
    content is the property value, and the property name is unused. As such, we represent an element as an array/list of values.

```tsx
const tableData: TableData = {
    caption: "Some elements from periodic table",
    head: ["Element position", "Atomic mass", "Symbol", "Element name"],
    body: [
        [6, 12.011, "C", "Carbon"],
        [7, 14.007, "N", "Nitrogen"],
        [39, 88.906, "Y", "Yttrium"],
        [56, 137.33, "Ba", "Barium"],
        [58, 140.12, "Ce", "Cerium"],
    ],
}
```

transforming an element as an object to an element as an array of values

```tsx
;(player) => [player.name, player.level, player.class]
```

### data prop

The table component receives the data in the data attribute. In that
case, it creates all the markup (head, body, rows) automatically.

```tsx
<Table data={tableData} />
```



# Paper

Encapsulate some UI to set it apart visually.

Paper sets a fill-color background.

In light mode, it sets a plain white \#FFF background. This matches the
light mode default background. As such, we either change the light mode
default background, or change the Paper background.

In dark mode, it sets a _dark.7_. Similarly, it matches the dark mode
default background. As such, we either change the dark mode default
background, or change the Paper background.

In addition to the background, we may set a pre-styled border and/or a
pre-styled shadow.

We usually add some padding, but nothing specific to Paper.

### props

-   `radius`, sets the background area radius. defaults to _sm_, aka 4px.
-   `shadow`, sets the size of a predefined shadow, if any. defaults to
    _none_.
-   `withBorder`, toggles a predefined border. defaults to _false_



# Accordion

### For each item, show a preview and allow disclosure of a detail panel.

The Accordion may contain one or several items, related or not. An item
shows up as a clickable preview (_Accordion.Control_) and embeds a
panel, hidden by default, that we toggle through clicking on the
preview.

In Mantine, the panel remains mounted regardless if it's toggled on or
off.

In Mantine, we set the chevron at the Accordion root, so it's shared
among all items

The panel may be a form. In that case, we may set the chevron as a plus
sign, to indicate we intend to add (submit) data to the server.

```tsx
Accordion variant="separated" chevron={<IconPlus/>}
	Accordion.Item value="item1"
		Accordion.Control
			Log Workout
		Accordion.Panel
			Content

	Accordion.Item value="item2"
		..
```



# Dark Color Palette

neutral gray

blueish gray

use in dark mode

The default overall background is <u>dark 7</u>. We may alternate the
background with <u>dark 8</u>.

Compared to the overall background, controls have a slightly lighter
one, <u>dark 6,</u> and may even be lighter on hover, <u>dark 5</u>.
Sometimes, hover goes to a darker background, such as <u>dark 8</u>,
such as for a select option.

The slider background is <u>dark 4</u>.

The text may be <u>white</u>, <u>dark 0</u>, <u>dark 1</u>, or <u>dark
2</u> for the most dimmed text. For example, we may have a <u>white</u>
title and a <u>dark 0</u> paragraph

The button label is <u>dark 0</u>.

The dimmed text is <u>dark 2</u>, such as secondary label, or secondary
text in general.

### revert to blue tinted dark palette

```tsx
const theme = createTheme({
    colors: {
        dark: [
            "#C1C2C5",
            "#A6A7AB",
            "#909296",
            "#5c5f66",
            "#373A40",
            "#2C2E33",
            "#25262b",
            "#1A1B1E",
            "#141517",
            "#101113",
        ],
    },
})
```



# Bar Chart

packages

```pug
@mantine/charts
recharts
```

stylesheet

```tsx
import "@mantine/charts/styles.css"
```

### bar-chart logic

for each index, display one or several bars. We assume one bar for each
index.

### data for a given index

The chart library expects an object for each index. The object contains
raw data. Among this data, we select which property acts as the label.
The remaining properties may act as magnitude.

```tsx
{month: "Jan", workouts: 17},
{month: "Feb", workouts: 18}
```

### indicate data's shape

We indicate:

-   the property that acts as the label, here <u>month</u>
-   for each property that we want to act as a magnitude, we indicate: the
    property's name (here <u>workouts)</u> the color for that bar, and the
    label for that bar.

In the following example, _workouts_ provides the magnitude for the
unique serie.

```tsx
<BarChart
    data={}
    h={300}
    dataKey="month" // key that provides label
    series={[
        // bar(s) configuration
        { name: "workouts", color: "blue.6", label: "Workouts" },
    ]}
/>
```

Each magnitude's property, as it spreads over all the indexes, makes a
distinct serie. For example, the ipadSales, the iponeSales, and the
macSales make each one a distinct serie.



# Progress

### simple progress bar

-   `value`: from 0 to 100
-   `size`: the vertical size, aka how thick it is. Defaults to `8px` through default _md_.
-   `radius`: defaults to `4px` through default _sm_. The default size and radius lead to a perfect semi circle border.
-   `color`: defaults to `blue`
-   `animated`: enable a striped pattern and animate the stripes.
-   `striped`: enable a striped pattern.
-   `transitionDuration`: set the duration of the animation that occurs when the value changes, in ms. Defaults to 100.

```tsx
<Progress value={50} />
```

### compound progress bar • segmented bar

We may have several segments.

-   The container is `Progress.Root`
-   Each segment is a `Progress.Section`
-   We may add a segment label with `Progress.Label`

We may make the label have a smart color with `autoContrast`.

```tsx
<Progress.Root>
    <Progress.Section value={20} color="indigo">
        <Progress.Label>Documents</Progress.Label>
    </Progress.Section>
    <Progress.Section value={50} color="orange">
        <Progress.Label>Photos</Progress.Label>
    </Progress.Section>
</Progress.Root>
```



# Pagination

we provide:

-   the `total` number of pages
-   the `value` of the cursor aka selected page number.
-   the `onChange` handler
-   (optional) `withControls`, to show previous and next arrows, defaults to
    true.
-   (optional) `withEdges`, to show first and last arrows, default to false.
-   (optional) `size`, to get bigger or smaller pagination control, defaults
    to _md_
-   (optional) `radius`, to get rounder or squarer controls, defaults to
    _md_

```tsx
const [activePage, setActivePage] = useState<number>(1)
```

```tsx
<Pagination total={10} value={activePage} onChange={setActivePage} />
```



# Default theme

[<u>https://mantine.dev/theming/default-theme/</u>](https://mantine.dev/theming/default-theme/)

### spacing

used for:

-   `gap` in Group, Flex, Stack.
-   padding style props such a _p_.
-   margin style props such as _m_, notably for Divider
-   width and height props such as _w_ and _h_, notably for Space.

```tsx
xs: 10px
sm: 12px
md: 16px
lg: 20px
xl: 32px
```

### radius

used for:

-   Paper
-   Dialog, Modal, ..
-   Button, Tooltip..

the default radius is _sm_, aka 4px.

```tsx
"defaultRadius": "sm",
```

mantine provides a lit of sensible values

```tsx
xs: 2px
sm: 4px (d)
md: 8px
lg: 16px
xl: 32px
```

### breakpoints

determines from which point onward to activate desktop mode.

Some behaviour only makes sense in desktop, such as always-on navbar.

The _sm_ breakpoint activates desktop mode from 768px onwards.

iPads have at least 768px width. As such, they will activate desktop
mode. iPad users enjoy the desktop UI because their bigger screen make
it reasonable.

```tsx
  "breakpoints": {
    "xs": "36em", // 576px
    "sm": "48em", // 768px
    "md": "62em",
    "lg": "75em",
    "xl": "88em"
  },
```

### font sizes: a set of 5 distinct values.

a set of font sizes, for body text or UI elements other than titles.

used for:

the _fz_ inline prop.

the middle ground _md_ is 16px.

```tsx
"fontSizes": {
    "xs": 12px
    "sm": 14px
    "md": 16px,
    "lg": 18px
    "xl": 20px
  },
```

the level of indirection might not be worth it. It may be better to
directly state 12, 14 or 16 directly.



# Global Style: Colors

dark mode

```css
--mantine-color-scheme: dark;
--mantine-primary-color-contrast: var(--mantine-color-white);
--mantine-color-bright: var(--mantine-color-white);
--mantine-color-text: var(--mantine-color-dark-0);
--mantine-color-body: var(--mantine-color-dark-7);
--mantine-color-error: var(--mantine-color-red-8);
--mantine-color-placeholder: var(--mantine-color-dark-3);
--mantine-color-anchor: var(--mantine-color-blue-4);
--mantine-color-default: var(--mantine-color-dark-6);
--mantine-color-default-hover: var(--mantine-color-dark-5);
--mantine-color-default-color: var(--mantine-color-white);
--mantine-color-default-border: var(--mantine-color-dark-4);
--mantine-color-dimmed: var(--mantine-color-dark-2);
--mantine-color-dark-text: var(--mantine-color-dark-4);
--mantine-color-dark-filled: var(--mantine-color-dark-8);
--mantine-color-dark-filled-hover: var(--mantine-color-dark-7);
--mantine-color-dark-light: rgba(36, 36, 36, 0.15);
--mantine-color-dark-light-hover: rgba(36, 36, 36, 0.2);
--mantine-color-dark-light-color: var(--mantine-color-dark-3);
--mantine-color-dark-outline: var(--mantine-color-dark-4);
--mantine-color-dark-outline-hover: rgba(36, 36, 36, 0.05);
--mantine-color-gray-text: var(--mantine-color-gray-4);
--mantine-color-gray-filled: var(--mantine-color-gray-8);
--mantine-color-gray-filled-hover: var(--mantine-color-gray-9);
--mantine-color-gray-light: rgba(134, 142, 150, 0.15);
--mantine-color-gray-light-hover: rgba(134, 142, 150, 0.2);
--mantine-color-gray-light-color: var(--mantine-color-gray-3);
--mantine-color-gray-outline: var(--mantine-color-gray-4);
--mantine-color-gray-outline-hover: rgba(206, 212, 218, 0.05)
--mantine-color-red-text: var(--mantine-color-red-4);
```

### body background

lightmode: white \#FFF

darkmode: dark.7

### body text color

lightmode: black \#000

darkmode: dark.0

### dimmed text color

dark.2



# Global style: Others

line-height defaults to 1.55

```css
--mantine-line-height: 1.55;
```


Mantine

Syntax

GitHub Flavored Markdown (GFM)

# Syntax

-   [markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
-   [github guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)

### headings

    # H1
    ## H2
    ### H3

### horizontal line

    ---

### inline code

    The call to `fetch()` was breaking the app.

The call to `fetch()` was breaking the app.

### block of code

    ```typescript
    <Box>Hello World!</Box>
    ```

```typescript
<Box>Hello World!</Box>
```

| language specifier |
| ------------------ |
| typescript         |
| javascript         |
| tsx                |
| jsx                |
| bash               |



# GitHub Flavored Markdown (GFM)

it adds features such as code blocks with three backticks. It's the
prevalent syntax, and is adopted by github and discord.
