# Styling in Cardboard.js <!-- omit in toc -->

Cardboard.js offers a flexible, powerful approach to styling your UI—without writing CSS files or using JSX. You can style elements directly with JavaScript objects, use dynamic styles based on state, and even manage global or reusable styles with ease.

This guide covers all the main concepts, best practices, and common pitfalls for styling in Cardboard.js.

### Table of contents <!-- omit in toc -->
- [Inline Styles with `.addStyle` and `.setStyle`](#inline-styles-with-addstyle-and-setstyle)
- [Styling with Classes and global `<style>` Tags](#styling-with-classes-and-global-style-tags)
- [Dynamic Styles Based on State](#dynamic-styles-based-on-state)
- [Removing and Replacing Styles](#removing-and-replacing-styles)
- [Best Practices](#best-practices)
  - [Prefer Classes for Reusable Styles](#prefer-classes-for-reusable-styles)
  - [Use Inline Styles for Dynamic or One-off Styles](#use-inline-styles-for-dynamic-or-one-off-styles)
  - [Avoid Duplicating Inline Styles](#avoid-duplicating-inline-styles)
- [Advanced: Styling Child Elements](#advanced-styling-child-elements)
- [Example: Styled Component](#example-styled-component)
- [Example: Dynamic Styles](#example-dynamic-styles)
- [Example: Styling with State and Templates](#example-styling-with-state-and-templates)
- [Common Pitfalls](#common-pitfalls)
- [Reference: Style Methods](#reference-style-methods)
- [Summary](#summary)

---

## Inline Styles with `.addStyle` and `.setStyle`

You can add styles directly to any tag using `.addStyle` (for a single property) or `.setStyle` (for multiple properties):

```ts
div('Hello').addStyle('color', 'blue');
div('Box').setStyle({
    backgroundColor: 'lightgray',
    padding: '10px',
    borderRadius: '4px',
});
```

**Bad Practice:**  
Avoid chaining many `.addStyle` calls for the same element:
```ts
// ❌ Not recommended
div('Bad').addStyle('color', 'red').addStyle('fontWeight', 'bold');
```

**Good Practice:**  
Use `.setStyle` for multiple properties to keep your code clean.
```ts
// ✅ Recommended
div('Bad').setStyle({
    color: 'red',
    fontWeight: 'bold',
});
```

---

## Styling with Classes and global `<style>` Tags

For global styles, define a CSS class in a `<style>` tag and use `.addClass`:

```ts
tag('(head)').append(style({
    '.fancy': {
        color: 'purple',
        fontWeight: 'bold',
        border: '1px solid purple',
        borderRadius: '6px',
        padding: '6px 12px',
    }
}));

const FancyBox = () => div('Reusable!').addClass('fancy');
```

**Bad Practice:**  
Avoid duplicating inline styles for every instance of a component.

---

## Dynamic Styles Based on State

Cardboard.js makes it easy to update styles reactively using `.styleIf`, `.styleIfNot`, `.stylesIf`, and `.stylesIfNot`:

```ts
const count = state(0);

button('Click me')
    .addStyle('color', 'gray')
    .stylesIf(count.greaterThan(5), { color: 'red' }) // color turns red if count > 5
    .clicked(() => count.value++);
```

- `.styleIf(observable, property, value)` — Adds a style when the observable is truthy.
- `.styleIfNot(observable, property, value)` — Adds a style when the observable is falsy.
- `.stylesIf(observable, styleMap)` — Adds multiple styles when observable is truthy.
- `.stylesIfNot(observable, styleMap)` — Adds multiple styles when observable is falsy.

**Example:**

```ts
const isActive = state(false);

div('Toggle me')
    .styleIf(isActive, 'backgroundColor', 'green')
    .styleIfNot(isActive, 'backgroundColor', 'gray')
    .clicked(() => isActive.value = !isActive.value);
```

---

## Removing and Replacing Styles

- `.rmStyle('property')` — Removes a style property.
- `.replaceClass('old', 'new')` — Replaces a class.
- `.toggleClass('className')` — Adds or removes a class.

**Example:**

```ts
div('Toggle highlight')
    .toggleClass('highlighted');
```

---

## Best Practices

### Prefer Classes for Reusable Styles

If you have a component used in many places, define a class and use `.addClass`. This keeps your DOM cleaner and improves performance.

```ts
// ❌ Bad
const Card = (content) => div(content).setStyle({ ... });

// ✅ Good
tag('(head)').append(style({
    '.card': { ... }
}));
const Card = (content) => div(content).addClass('card');
```

You can also use the `.styled` method on the tag to accomplish the same thing in a more direct way:

```ts
// ✅ Better ✅
const Card = (content) => div(content).styled({ ... });
```

### Use Inline Styles for Dynamic or One-off Styles

If a style is unique to a single element or depends on state, inline styles are fine.

```ts
div('Dynamic')
    .setStyle({ color: 'blue', fontWeight: 'bold' })
    .styleIf(isError, 'color', 'red');
```

### Avoid Duplicating Inline Styles

Don't repeat the same inline style across many components. Use classes instead.

---

## Advanced: Styling Child Elements

You can style child elements using nested selectors in your style object:

```ts
style({
    '.parent': {
        backgroundColor: 'beige',
        padding: '10px',
        '.child': {
            color: 'navy',
            fontWeight: 'bold',
        }
    }
});
```

---

## Example: Styled Component

```ts
const StyledThing = () => div('This is a styled component')
    .styled({
        backgroundColor: 'lightblue',
        padding: '10px',
        borderRadius: '5px',
        boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)',
        fontFamily: 'Arial, sans-serif',
        fontSize: '16px',
        color: 'darkslategray',
        textAlign: 'center',
        margin: '10px 0',
    });

init().append(
    StyledThing(),
    StyledThing(),
);
```

---

## Example: Dynamic Styles

```ts
const isWarning = state(false);

const WarningBox = () =>
    div('Warning!')
        .setStyle({ padding: '8px', borderRadius: '4px' })
        .styleIf(isWarning, 'backgroundColor', 'orange')
        .styleIfNot(isWarning, 'backgroundColor', 'lightgray')
        .clicked(() => isWarning.value = !isWarning.value);

init().append(WarningBox());
```

---

## Example: Styling with State and Templates

```ts
const count = state(0);

button()
    .text('Clicked $count times', { count })
    .setStyle({ color: 'gray' })
    .stylesIf(count.greaterThan(5), { color: 'red' })
    .clicked(() => count.value++);
```

---

## Common Pitfalls

- **Don't use inline styles for every instance of a reusable component.**  
    This can lead to performance issues and messy DOM.
- **Don't forget to use `.addClass` or `.styled` for global styles.**
- **Avoid mixing too many style methods on the same element.**  
    Prefer `.setStyle` for multiple properties.

---

## Reference: Style Methods

| Method                | Description                                 |
| --------------------- | ------------------------------------------- |
| `.addStyle(k, v)`     | Add a single style property                 |
| `.setStyle(obj)`      | Set multiple style properties               |
| `.rmStyle(...keys)`   | Remove one or more style properties         |
| `.hasStyle(...keys)`  | Check if element has given style(s)         |
| `.styleIf(...)`       | Add style if observable is truthy           |
| `.styleIfNot(...)`    | Add style if observable is falsy            |
| `.stylesIf(...)`      | Add multiple styles if observable is truthy |
| `.stylesIfNot(...)`   | Add multiple styles if observable is falsy  |
| `.addClass(name)`     | Add a class                                 |
| `.rmClass(name)`      | Remove a class                              |
| `.replaceClass(a, b)` | Replace class `a` with `b`                  |
| `.toggleClass(name)`  | Toggle a class                              |

---

## Summary

- Use `.setStyle` and `.addStyle` for quick, dynamic, or one-off styles.
- Use classes and `<style>` for reusable, global, or shared styles.
- Use `.styleIf` and `.stylesIf` for state-driven dynamic styling.
- Avoid duplicating inline styles for reusable components.

For more, see the [Cardboard.js Wiki](https://github.com/nombrekeff/cardboard-js/wiki) and [API Docs](https://nombrekeff.github.io/cardboard-js/).