Designing for Different Devices (Touch & Hover)

Documentation Developer Guides
1

This document outlines the APIs used to adapt Discourse’s user interface for different devices.

Touch & Hover

Some devices only have touchscreens, some only have a traditional mouse pointer, and some have both. Importantly, touchscreen users cannot “hover” over elements. Therefore, interfaces should be designed to work entirely without hover states, with hover-specific enhancements added for devices that support them.

There are several ways to detect touch/hover capability via CSS and JavaScript. For consistency, we recommend using Discourse’s helpers instead of those CSS/JS APIs directly.

For CSS, you can target the .discourse-touch and .discourse-no-touch classes, which are added to the <html> element. These are determined based on the (any-pointer: coarse) media query.

For example:

html.discourse-touch {
  // SCSS rules here will apply to devices with a touch screen,
  // including mobiles/tablets and laptops/desktops with touch screens.
}

html.discourse-no-touch {
  // SCSS rules here will apply to devices with no touch screen.
}

This information is also available in Ember components via the capabilities service:

import Component from "@glimmer/component";
import { service } from "@ember/service";

class MyComponent extends Component {
  @service capabilities;

  <template>
    {{#if this.capabilities.touch}}
      This text will be displayed for devices with a touch screen
    {{/if}}

    {{#unless this.capabilities.touch}}
      This text will be displayed for devices with no touch screen
    {{/unless}}
  </template>
}

Legacy Mobile / Desktop Modes

Historically, Discourse shipped two completely different layouts and stylesheets for “mobile” and “desktop” views, based on the browser’s user-agent. Developers would target these modes by putting CSS in specific mobile/desktop directories, by using the .mobile-view/.desktop-view HTML classes, and the site.mobileView boolean in JavaScript.

These techniques are now considered deprecated and should be replaced with the viewport and capability-based strategies discussed in the next document. For backwards-compatibility, legacy desktop/mobile CSS is used when the viewport is larger/smaller than the sm threshold.

See also

This document is version controlled - suggest changes on github.

12 Likes
Chrome console deprecation warnings on Discourse v2026.1.0-latest (+307)
Claude & Discourse-related development. How good is it?
Inline PDF Previews
Force Mobile Homepage
Change share icon by OS
控制台报错，site.mobileView/site.desktopView功能异常
Which browser loads the correct mobile display?
Discourse Livestream
Improving automatic switching of mobile/desktop modes
Process Manager :left_right_arrow: - formerly "Discourse Workflow"
Show both OP and last reply on mobile
Discourse Tab Bar for Mobile
Show both OP and last reply on mobile
Is there a way to enable a component only on mobile?
Is there a way to enable a component only on mobile?
I am not able to disable flair or user titles on mobile
2

So something like this would be deprecated?

@service site;
...
const mobileView = this.site.mobileView;
3

If you do it in a static context like an initializer, then yes, that’s not going to be compatible with the upcoming “viewport based mobile mode” (currently disabled by default, but will be enabled soon).

If you do the check in an autotracking context like this:

@service site;
...
<template>
  {{#if this.site.mobileView}}
    ...
  {{/if}}
</template>

Then Ember will automatically re-render things when the mobileView boolean changes (i.e. when the browser is resized). So that’s fine.

4

So just to be sure, putting it in a getter is deprecated, but not putting it in <template>?

5

Putting it in a getter is also fine, since that’ll be autotracked by Ember.

@service site;

get shouldRender(){
  return this.site.mobileView;
}

<template>
  {{#if this.shouldRender}}
    ...
  {{/if}}
</template>

^^ this is fine

A bad example would be

export default apiInitializer((api) => {
  const site = api.container.lookup("service:site");
  if(site.mobileView){
    api.renderInOutlet("some-outlet", <template>My content</template>)
  }
});

Because in this situation, mobileView is only checked when the application boots. Resizing the browser won’t re-run the initializer.

So you would refactor to something like

export default apiInitializer((api) => {
  const site = api.container.lookup("service:site");
  api.renderInOutlet("some-outlet", <template>
    {{#if site.mobileView}}My content{{/if}}
  </template>);
});

That way: changes to mobileView will take effect when the browser is resized.

An easy way to test all this: enable “viewport based mobile mode” site setting, then try resizing your browser and check that the layout updates correctly when you go between narrow/wide browser widths.

3 Likes
6

Understood now. Thanks for the explanation!

1 Like
7

“Deprecation notice: Accessing capabilities.viewport.sm during the site initialization phase is not recommended. Using these values during initialization can lead to errors and inconsistencies when the browser window is resized. Please move these checks to a component, transformer, or API callback that executes during page rendering. [deprecation id: discourse.static-viewport-initialization]”

I’ve been using initialisers to switch on and off various functionality based on whether we are in a mobile view or not (e.g. changing the default Homepage, adding a community section link for example). These aren’t really meant to be dynamic and reactive - suggestions welcome on how to treat these use cases and make sure I can defeat this notice.

1 Like
8

The general recommendation is: don’t do that. Why should those kind of experiences differ based on the size of the screen?

A useful thought experiment is: how do you expect it to behave on folding phones or tablets, which don’t explicitly fit into the mobile/desktop buckets.

If you really do want this kind of behaviour change to be based on the user-agent of the browser (as the old mobile/desktop modes worked), then we have capabilities.isMobileDevice, which quite literally checks for the word “mobile” in the user-agent string:

1 Like
9

well in my case it’s that I provide the option for desktop to switch homepage to the tag intersections route - whose interface doesn’t exist on mobile … (though the route actually works - additional controls are hidden)

… but point taken, I’ll probably rethink this!

1 Like
10

Interesting! I wonder if that’s deliberate… I feel like it should work on any device :thinking:

2 Likes
11

so does this mean Discourse is going to deprecate pull-left? because that class is kind of horrible to work with and i’d love to see it gone.

12

that would be really nice :wink:

13

The solution is in the message

Instead of conditionally including the component, always include it, and have the component conditionally render itself.

1 Like
14

I hear you, but I don’t own this component, it’s part of core and on a specific route - if core were to make this work on mobile and desktop that would be the best solution.

As it stands you can make this page the homepage (globally) but on mobile that is pointless as it doesn’t work.

15

I’ll give you another example where this is currently not fully exploited and a little tricky - Categories page - on desktop leave as is but maybe turn it into a Latest page on mobile by hiding the Categories panel and just leave the Topic List - since only having the Categories view and no Topic List (on mobile) imho sucks (as a home page).

But then on mobile this wouldn’t be a “Categories” page anymore (despite the route name) :thinking:

This is now exacerbated by the fact that the force mobile home page theme component doesn’t work any more because you can’t identify the device during init.

I think therefore that the discovery routes may need some kind of rethink for interoperability and suitability for the prevailing device.

2 Likes