# How to Pass Nitter User Preferences via URL Parameters

> Learn how to pass Nitter user preferences via URL parameters. Customize your Nitter experience for any request by adding query strings like ?theme=dark to any Nitter URL.

- Repository: [Zed/nitter](https://github.com/zedeus/nitter)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Nitter user preferences can be passed as URL parameters by appending query strings such as `?theme=dark&hideRetweets=1` to any Nitter URL, temporarily overriding cookie-based settings for that specific request.**

The zedeus/nitter repository implements a flexible preference system that allows visitors to customize their viewing experience without creating accounts. When you leverage Nitter user preferences URL parameters, you create shareable, customized views that modify themes, content filtering, and media behavior without altering the recipient's permanent settings stored in browser cookies.

## How URL Parameters Override Cookie Settings

When a request arrives at a Nitter instance, the application builds a **Prefs** object that controls rendering behavior. According to the source code in `src/prefs_impl.nim`, this object is populated through a two-stage process:

- **Cookies** provide the base values from previous visits
- **Query-string parameters** override cookie values for the current request

Because query parameters are applied after cookies are read, they act as temporary, per-request overrides. This architecture enables link-sharing with forced preferences while preserving user defaults.

### The Prefs Object in src/prefs.nim

The `Prefs` type is defined in `src/prefs.nim`, which declares fields such as `theme`, `hideReplies`, `autoplayGifs`, and `proxyVideos`. Each field corresponds directly to a URL parameter key using a one-to-one naming convention. When the parsing routine iterates over `request.queryParams`, it maps each query key to its matching field in the structure.

### Query String Parsing Logic in src/prefs_impl.nim

The parsing implementation handles type conversion automatically. For boolean fields like `hideRetweets` or `muteVideos`, the parser in `src/prefs_impl.nim` accepts multiple representations:

- **True values**: `1`, `true`, `on`
- **False values**: `0`, `false`, `off`

String fields such as `theme` pass their values directly to the view templates, which expect CSS theme identifiers like `light`, `dark`, or `solarized`.

## Available Nitter User Preferences URL Parameters

The following query parameters correspond to fields defined in `src/prefs.nim`:

| URL Parameter | Prefs Field | Accepted Values |
|---------------|-------------|-----------------|
| `theme` | `theme` | CSS theme strings (`light`, `dark`, `solarized`) |
| `hideRetweets` | `hideRetweets` | Boolean (`1`/`true`/`on` or `0`/`false`/`off`) |
| `hideReplies` | `hideReplies` | Boolean |
| `hidePins` | `hidePins` | Boolean |
| `autoplayGifs` | `autoplayGifs` | Boolean |
| `proxyVideos` | `proxyVideos` | Boolean |
| `muteVideos` | `muteVideos` | Boolean |
| `gallerySize` | `gallerySize` | String (`small`, `medium`, `large`, `compact`) |
| `compactGallery` | `compactGallery` | Boolean |
| `hideCommunityNotes` | `hideCommunityNotes` | Boolean |

Additional preference fields defined in `src/prefs.nim` are exposed through the same mechanism, allowing comprehensive customization via URL.

## Practical URL Examples

To apply preferences without changing cookie settings, append the appropriate query parameters to any Nitter URL:

```text
https://nitter.net/username?theme=dark&hideRetweets=1

```

This link forces the dark theme and hides retweets for the profile view.

```text
https://nitter.net/search?q=nim&autoplayGifs=0&gallerySize=compact

```

This search URL disables GIF autoplay and uses compact gallery sizing.

```text
https://nitter.net/hashtag/nim?proxyVideos=1&muteVideos=1

```

This hashtag view proxies video content and mutes playback by default.

## Technical Implementation in Views

After parsing in `src/prefs_impl.nim`, the populated **Prefs** object is passed to all view rendering functions. Files such as `src/views/tweet.nim` and `src/views/timeline.nim` receive this object as an argument and adapt their output accordingly—modifying avatar rendering, media playback controls, and layout density based on the supplied preferences. The preferences route handler in `src/routes/preferences.nim` provides the available theme list, while `src/views/preferences.nim` renders the settings UI for users who wish to save permanent cookies.

## Summary

- Nitter user preferences URL parameters temporarily override cookie settings for individual requests
- The `src/prefs_impl.nim` file implements the parsing logic that processes query strings after cookies are loaded
- Boolean parameters accept `1`/`true`/`on` for true and `0`/`false`/`off` for false values
- String parameters like `theme` and `gallerySize` accept specific CSS theme names and size descriptors
- View files receive the final Prefs object to customize rendering without persistent storage

## Frequently Asked Questions

### Do URL parameters override existing cookie preferences?

Yes. According to the implementation in `src/prefs_impl.nim`, the application reads cookie values first, then iterates over query-string parameters to update the Prefs object. This ensures that URL parameters act as per-request overrides while leaving permanent cookie settings unchanged.

### What boolean formats does Nitter accept in URL parameters?

The parser in `src/prefs_impl.nim` recognizes three representations for boolean values. Use `1`, `true`, or `on` to enable a feature, and `0`, `false`, or `off` to disable it. All three formats are functionally equivalent for any boolean preference field.

### Can I combine multiple preferences in a single URL?

Yes. Chain multiple parameters using ampersand (`&`) separators. For example, `?theme=dark&hideReplies=1&autoplayGifs=0` applies all three preferences simultaneously to the requested timeline or profile view.

### Are preference changes made via URL parameters permanent?

No. Changes passed through Nitter user preferences URL parameters affect only the current request. To save settings permanently, users must visit the `/preferences` page, which is handled by `src/routes/preferences.nim` and rendered by `src/views/preferences.nim` to set browser cookies.