> For the complete documentation index, see [llms.txt](https://infinitode-docs.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://infinitode-docs.gitbook.io/documentation/package-documentation/qrforge-package-documentation/qrforge-reference/qrforge-style-options.md).

# qrforge Style Options

Every style option qrforge exposes, grouped by modules, eyes, colours, textures, logos, effects and geometry — with default values.

A `Style` is a plain dataclass holding every knob qrforge exposes. You can pass individual options as keywords, hand several renders the same `Style`, or start from a [preset](/documentation/package-documentation/qrforge-package-documentation/qrforge-reference/qrforge-presets-and-outputs.md#presets) and override what you need.

```python
import qrforge

# keywords
qr = qrforge.QR("hello").use_style(module_shape="dot", fg=["#ff0080", "#7928ca"])

# a reusable Style
style = qrforge.Style(module_shape="dot", fg=["#ff0080", "#7928ca"])
qr.style                                     # the current Style
style.copy(module_scale=0.5)                 # copy with overrides
style.merged(module_shape="star")            # merged copy
style.to_dict()                              # all fields
style.to_dict(include_defaults=False)        # only what differs from the defaults
qrforge.style.options()                      # every valid field name
```

`qr.use_style(...)` merges into the current style; `qr.styled(...)` returns a new `QR` instead.

Anything a style field accepts as a colour also accepts a gradient: a single colour becomes a solid fill, a list of colours becomes a linear gradient, and a dict configures the gradient.

***

## Modules

| Option            | Default    | Description                                                                                                                            |
| ----------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `module_shape`    | `'square'` | Shape of the data modules: a name from `qrforge.shapes.SHAPES`, a `Shape`, an SDF callable, or a list of those to pick from at random. |
| `module_scale`    | `1.0`      | Size of the shape inside its cell (`1.0` = modules touch, `0.8` = gaps).                                                               |
| `module_gap`      | `0.0`      | Extra inset in module units.                                                                                                           |
| `module_radius`   | `None`     | Corner radius in module units (used by rounded shapes such as `rounded`, `bar_v`, `bar_h`).                                            |
| `module_rotation` | `0.0`      | Rotation of every module, in degrees.                                                                                                  |
| `module_jitter`   | `0.0`      | `0`–`1` random variation of scale/rotation per module.                                                                                 |
| `function_shape`  | `None`     | Draw function modules (timing, format, alignment) with a different shape.                                                              |
| `function_fg`     | `None`     | Colour source for function modules; defaults to `fg`.                                                                                  |
| `invert`          | `False`    | Reserved — accepted by `Style` but not applied by the renderers in 1.0.1.                                                              |

```python
qr.use_style(module_shape=["dot", "star", "hexagon"], seed=3, module_jitter=0.2,
             module_scale=0.92, function_shape="bar_h")
```

***

## Eyes

The three finder patterns ("eyes") are styled independently from the data modules.

| Option          | Default | Description                                                                  |
| --------------- | ------- | ---------------------------------------------------------------------------- |
| `eye_shape`     | `None`  | Shape of the three finder patterns; `None` derives it from the module shape. |
| `eye_dot_shape` | `None`  | Shape of the dot in the middle of an eye; `None` follows `eye_shape`.        |
| `eye_ring`      | `1.0`   | Thickness of the eye ring, in module units.                                  |
| `eye_scale`     | `1.0`   | Scale of the whole eye.                                                      |
| `eye_dot_scale` | `1.0`   | Scale of the centre dot.                                                     |
| `eye_fg`        | `None`  | Separate colour source for the eyes; defaults to `fg`.                       |
| `eye_padding`   | `0.0`   | Reserved — accepted by `Style` but not applied by the renderers in 1.0.1.    |

```python
qr.use_style(eye_shape="rounded", eye_dot_shape="circle",
             eye_ring=1.1, eye_scale=0.95, eye_dot_scale=1.1, eye_fg="#00ff88")
```

***

## Colours & canvas

| Option        | Default     | Description                                                                       |
| ------------- | ----------- | --------------------------------------------------------------------------------- |
| `fg`          | `'#101014'` | Colour, gradient (list of colours) or gradient dict for the modules.              |
| `bg`          | `'#ffffff'` | Background colour/gradient, or `None` for transparency.                           |
| `bg_image`    | `None`      | Background image (path, bytes, PIL image or `Pixmap`).                            |
| `bg_opacity`  | `1.0`       | Opacity of the background image/colour.                                           |
| `bg_radius`   | `0.0`       | Corner radius of the background card, as a fraction of the symbol width.          |
| `padding`     | `0.0`       | Extra padding around the symbol, in module units.                                 |
| `quiet_zone`  | `4`         | Quiet zone in modules (the QR spec asks for `4`).                                 |
| `scale`       | `8`         | Pixels per module for raster output.                                              |
| `supersample` | `1`         | Supersampling factor used when rasterising shapes (`1` = analytic anti-aliasing). |

```python
qr.use_style(bg="#0a0118", padding=2, bg_radius=0.06, quiet_zone=4,
             shadow={"color": "#000000", "dy": 6, "blur": 5, "opacity": 0.25})
```

***

## Texture

A texture is painted *inside* the dark modules instead of a flat `fg`.

| Option            | Default    | Description                                                                                     |
| ----------------- | ---------- | ----------------------------------------------------------------------------------------------- |
| `texture`         | `None`     | Image painted inside the modules instead of `fg`.                                               |
| `texture_mode`    | `'cover'`  | `cover`, `contain` or `stretch`.                                                                |
| `texture_opacity` | `1.0`      | Opacity of the texture, `0`–`1`.                                                                |
| `texture_blend`   | `'source'` | How the texture mixes with `fg`: `source`, `multiply`, `screen`, `overlay` or `tint` (average). |
| `texture_global`  | `True`     | Reserved — accepted by `Style` but not applied by the renderers in 1.0.1.                       |

***

## Logo

The logo is a knockout: modules underneath are cleared, with an optional background and stroke, so the image stays readable.

| Option          | Default     | Description                                                                                   |
| --------------- | ----------- | --------------------------------------------------------------------------------------------- |
| `logo`          | `None`      | Logo image (path, bytes, PIL image or `Pixmap`).                                              |
| `logo_size`     | `0.22`      | Logo width as a fraction of the symbol width.                                                 |
| `logo_radius`   | `0.0`       | Corner radius of the logo cut-out, in module units.                                           |
| `logo_padding`  | `0.75`      | Clear zone around the logo, in module units.                                                  |
| `logo_bg`       | `'#ffffff'` | Colour behind the logo; `None` keeps whatever is underneath.                                  |
| `logo_shape`    | `'square'`  | `square`, `circle` or `rounded`.                                                              |
| `logo_rotation` | `0.0`       | Rotation of the logo, in degrees.                                                             |
| `logo_opacity`  | `1.0`       | Opacity of the logo image, `0`–`1`.                                                           |
| `logo_stroke`   | `None`      | Stroke around the logo cut-out: `(colour, width_in_modules)`.                                 |
| `logo_position` | `'center'`  | `"center"`, or an `(x, y)` fraction of the symbol size. Honoured by the raster renderer only. |

{% hint style="info" %}
Use `ec="h"` and keep `logo_size` around `0.22`–`0.30`, then check `qr.verify()` — logos cover data modules.
{% endhint %}

***

## Effects

| Option    | Default | Description                                                                                                                                                                                                                                     |
| --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shaders` | `()`    | Shaders applied in order: names, `"name:key=value"` strings, callables or `Shader` objects. See [Shapes & Shaders](/documentation/package-documentation/qrforge-package-documentation/qrforge-reference/qrforge-shapes-and-shaders.md#shaders). |
| `shadow`  | `None`  | Drop shadow: `{"color": …, "dx": …, "dy": …, "blur": …, "opacity": …}`.                                                                                                                                                                         |
| `stroke`  | `None`  | Outline/stroke drawn around modules, as `(colour, width_in_modules)`.                                                                                                                                                                           |
| `seed`    | `None`  | Seed for every randomised effect; `None` picks one at random.                                                                                                                                                                                   |

```python
qr.use_style(
    shaders=["glow:radius=2,amount=0.75", "grain:amount=0.06"],
    stroke=("#ffffff", 0.1),
    seed=7,
)
```

***

## Reserved options and renderer coverage

| Option                                                              | Status in 1.0.1                                                          |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `invert`                                                            | Accepted, not applied by any renderer.                                   |
| `eye_padding`                                                       | Accepted, not applied by any renderer.                                   |
| `texture_global`                                                    | Accepted, not applied by any renderer (textures are sampled per symbol). |
| `logo_position`                                                     | Raster only; SVG always centres the logo.                                |
| `supersample`                                                       | Raster only.                                                             |
| Warp/post shaders such as `twist`, `bulge`, `glitch` and `halftone` | Raster only; SVG has no equivalent filter, so they are skipped there.    |

**Style helpers:** `style.copy(**overrides)`, `style.merged(other=None, **overrides)`, `style.to_dict(include_defaults=True)`, `style.seed_or(default=0)` and `qrforge.style.options()`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://infinitode-docs.gitbook.io/documentation/package-documentation/qrforge-package-documentation/qrforge-reference/qrforge-style-options.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.