Building Responsive Layouts with the OutSystems Grid System

OutSystems UI uses a 12-column grid. Every Container widget placed on a screen can be assigned a column width from 1 to 12. Widgets in the same row share the 12 columns: - A single Container set to 12 columns spans the full width - Two Containers each set to 6 columns sit side by side (50% each) - Three Containers each set to 4 columns create a three-column layout - A Container set to 8 and one set to 4 creates a classic sidebar layout **Breakpoints in OutSystems UI:** | Name | Width range | Class suffix | |---|---|---| | Phone | up to 767px | -phone | | Tablet | 768px – 1023px | -tablet | | Desktop | 1024px and above | -desktop | The grid is mobile-first by default. Container width set in the Properties panel applies to all screen sizes. To override per breakpoint, use CSS media queries in your theme or the responsive helper classes. **View the grid in Service Studio:** Open any screen in the Screen Editor. The canvas shows column guides. In the Toolbox, search for 'Container' — drag one onto the screen and look at the 'Width' property in the Properties panel to see the column-based sizing.

Open a screen in the Screen Editor (Interface tab → UI Flows → MainFlow → double-click your screen). **Step 1 — Add a full-width header:** 1. Drag a Container from the Toolbox onto the screen canvas 2. In Properties panel → set Name to 'HeaderContainer' 3. In Properties panel → Styles tab → Width: 12 columns (full width) 4. Drag a Text widget inside the HeaderContainer, set Text to "Dashboard" 5. In Style Classes: `"font-size-h2 bold margin-bottom-m"` **Step 2 — Add a two-column content area:** 1. Drag a new Container below the HeaderContainer → Name: 'ContentRow' 2. Set ContentRow Style Classes: `"row"` (activates flex row layout) 3. Inside ContentRow, drag two Containers: - First: Name 'MainContent', Style Classes: `"col col-8"` (8 of 12 columns) - Second: Name 'Sidebar', Style Classes: `"col col-4"` (4 of 12 columns) **Column class format:** `col col-[n]` where n is 1–12. On phone screens, `col-[n]` classes default to full width (12 columns) automatically in the OutSystems UI grid — your layout stacks vertically on mobile without additional CSS.

1/* Widget tree for the two-column layout:
2
3   Container (HeaderContainer) — col 12
4     └─ Text: "Dashboard"
5
6   Container (ContentRow) — Style Classes: "row"
7     ├─ Container (MainContent) — Style Classes: "col col-8"
8     │   └─ [main content widgets here]
9     └─ Container (Sidebar) — Style Classes: "col col-4"
10         └─ [sidebar widgets here]
11*/

OutSystems provides built-in CSS classes that show or hide elements at specific breakpoints: - `.visible-desktop` — visible on desktop only (≥1024px) - `.visible-tablet` — visible on tablet only (768–1023px) - `.visible-phone` — visible on phone only (≤767px) - `.hidden-desktop` — hidden on desktop, visible on other sizes - `.hidden-phone` — hidden on phone, visible on other sizes These classes are applied to the widget's **Style Classes** property. **Common use cases:** **Desktop-only sidebar:** Select the Sidebar container → Style Classes: `"col col-4 hidden-phone"`. The sidebar disappears on phone screens. **Mobile-only compact header:** Add a second Header container designed for mobile → Style Classes: `"hidden-desktop"`. The compact header shows only on phones. **Alternative — the Visible property:** Every widget also has a boolean **Visible** property. Set it to an expression: `If(DeviceType = "Phone", False, True)`. However, using CSS helper classes is more performant since the widget is hidden with CSS rather than removed from the DOM.

1/* Responsive visibility class examples in Style Classes property */
2
3/* Show only on desktop: */
4"visible-desktop col col-4"
5
6/* Hide on phone (show on tablet + desktop): */
7"col col-4 hidden-phone"
8
9/* Show only on mobile: */
10"visible-phone"
11
12/* Responsive text sizing using OutSystems UI utilities: */
13"font-size-h3 visible-desktop font-size-h5 visible-phone"
14/* Note: use separate If expression for conditional font size */
15
16/* Expression for conditional Style Classes: */
17If(IsDesktop, "heading-desktop", "heading-mobile")

For per-widget sizing without writing CSS class names manually, use the **Styles Editor** in the Properties panel. 1. Select any widget on the screen canvas 2. In the Properties panel, click the **Styles tab** (paintbrush icon, second tab) 3. The Styles Editor shows visual controls for: Width, Height, Margin (top/right/bottom/left), Padding, Font, Color, Border, Shadow **Setting responsive width:** - In the Width field, enter `100%` for full width, `50%` for half, or `auto` - The Styles Editor adds inline styles — these override class-level CSS **Setting a max-width for readable content:** - Width: 100% - Max Width (in the Advanced section): 800px - Margin: 0 auto (centers the container) This is equivalent to the CSS: ``` .element { width: 100%; max-width: 800px; margin: 0 auto; } ``` Use the Styles Editor for one-off adjustments. For styles that apply to multiple widgets, always put the CSS in your Application Theme's Style Sheet Editor instead.

**Testing in browser:** 1. Publish your app with 1-Click Publish 2. Open in browser 3. Open DevTools (F12) → click the Device Toggle icon (phone/tablet icon in toolbar) 4. Select device presets: iPhone SE, iPad, or set custom viewport width 5. Verify: two-column layout collapses to single-column at phone width; hidden-phone elements disappear **Using the Theme Editor for global responsive settings:** 1. In Service Studio, Interface tab → Themes → double-click your theme 2. Click the **Theme Editor** button in the toolbar (paint palette icon) 3. The Theme Editor dialog opens with visual sliders for: - Primary/Secondary/Heading colors - Font family and base size - Spacing density (Compact / Regular / Comfortable) - Header size 4. Changes in the Theme Editor generate CSS variable overrides automatically — no manual CSS needed for these global settings **Responsive grid breakpoints in OutSystems UI (for reference when writing custom media queries):**

1/* OutSystems UI grid breakpoints — use in custom CSS when needed */
2
3/* Phone: up to 767px */
4@media (max-width: 767px) {
5  .dashboard-stats-row {
6    flex-direction: column;
7  }
8
9  .stat-card {
10    width: 100%;
11    margin-bottom: 12px;
12  }
13}
14
15/* Tablet: 768px to 1023px */
16@media (min-width: 768px) and (max-width: 1023px) {
17  .col-4 {
18    /* Override to show 2 columns on tablet instead of 3 */
19    flex: 0 0 50%;
20    max-width: 50%;
21  }
22}
23
24/* Desktop: 1024px and above */
25@media (min-width: 1024px) {
26  .page-container {
27    max-width: 1200px;
28    margin: 0 auto;
29  }
30}