You can style individual MDriven Turnkey controls in a Turnkey ViewModel by assigning documented modifier classes in the control's Style ref field; this page is for ViewModel authors who need component-level presentation without redefining the whole application theme.
Choose the right styling approach
Turnkey styling has two distinct purposes. Choose the approach that matches the change you need.
| Goal | Use | Example |
|---|---|---|
| Change one control or a small group of controls | A modifier class in the ViewModel control's Style ref | Show a status label with the tk-success text style.
|
| Change colours, type sizes, spacing, navigation, or other application-wide visual settings | Turnkey theming and CSS custom properties | Set the application primary colour once so it is used consistently. |
| Apply a style based on model data | A Style ref expression that returns a class name | Return a green style when an object is in a good state and a red style otherwise. |
| Change button label, visibility, enabled state, or style dynamically | button formatting and styling | Disable an action button through its formatting column. |
Do not use this page to duplicate theme definitions. For application-wide CSS variables, tkusercss.css, SCSS-based themes, deployment, and restoring the default theme, see Documentation:MDriven Turnkey theming. For an overview of styling across MDriven user interfaces, see Documentation:UI&Styling.
How Turnkey component classes are structured
The Turnkey Style System follows BEM: Block, Element, Modifier. BEM is a CSS naming convention that keeps a component's base styling separate from its parts and variations.
- A block is a self-contained component, such as a search box.
- An element is a part of that component. Its class name commonly uses
__, for exampletk-searchbox__input. - A modifier changes a component's appearance or state. Its class name commonly uses
--, for exampletk-searchbox--searching.
For example, a search input can use both its element class and a state modifier:
tk-searchbox__input tk-searchbox--searching
Use the documented classes exactly. The complete, current class catalogue and component recipes are maintained on Documentation:MDriven Stylesheet.
Apply a modifier class in a ViewModel
Use Style ref to attach a documented class to the ViewModel control that renders the element.
- Open the relevant ViewModel in MDriven Designer.
- Select the control to style, such as a static text, action button, link, GroupBox, or table column.
- Enter the required class or classes in the control's Style ref field.
- Run or refresh the Turnkey application and verify the rendered control.
- Keep the class in the ViewModel when it describes the control's purpose; move repeated visual values such as colours and sizes to the application theme instead.
For example, set the Style ref of a static status text to tk-success to present it with the success text styling. To combine compatible classes, separate them with spaces. A button can use primary outlined, while a primary flat button can use primary flat.
Important: Button and link modifier classes are intended for buttons and links. Use the documented tk--prefixed text classes when styling text. Do not apply a button presentation class to static text and expect it to behave as a button.
Style text and status information
Contextual text colours
Turnkey provides these contextual meanings:
| Context | Example use | Example text style |
|---|---|---|
| Danger | A validation or processing failure | tk-danger
|
| Warning | A condition that needs attention | tk-warning
|
| Success | A completed or healthy state | tk-success
|
| Info | Supplementary information for the user | tk-info
|
For example, a static text value of Import completed can use tk-success; a value of Import failed can use tk-danger. Change the colours behind these meanings through the application theme rather than redefining each label. Turnkey theming documents the contextual CSS custom properties.
Chips and typography
Use the text and chip modifier classes documented in Documentation:MDriven Stylesheet to make a status or process stage visible in a table or detail view. For example, a Pending status can be rendered as a chip so that users can scan a list of process stages.
The stylesheet also documents typography modifiers for headings and emphasis. Apply them to the text control that contains the value you want to present; do not change the global font settings when only one heading needs a different treatment.
Apply a style from data
A Style ref can be an expression when the visual state depends on the data. This lets one control change presentation without duplicating it in the ViewModel.
For example, the following OCL expression selects a style held in the ViewModel based on a Boolean condition:
self.ThingsAreSuperGreat->casetruefalse(selfVM.Styles.TheGreenStyle,selfVM.Styles.TheRedStyle)
Here, ThingsAreSuperGreat determines whether the control receives TheGreenStyle or TheRedStyle. Maintain reusable, data-driven styles in the model when several controls need the same rule. See Styling and Theming Your Application for this distinction between overall theme styling and styles that convey information from data.
Present Boolean values as a checkbox or switch
A Boolean attribute is rendered as a checkbox by default. To render the same Boolean attribute as a switch, add the TaggedValue Switch to its ViewModelColumn.
- Select the Boolean ViewModelColumn.
- Add the TaggedValue
Switch. - Run or refresh the Turnkey view and confirm that the Boolean is displayed as a switch.
Use the default checkbox when a compact binary input fits the form. Use a switch when the control represents an immediate on/off setting and the alternate presentation makes that state clearer.
Understand layout before overriding it
Turnkey normally uses CSS Grid to create the application layout. When you use placing containers, CSS flexbox becomes the core layout mechanism instead. This matters when you add styling: a grid-oriented adjustment may not produce the expected arrangement inside a placing container.
Start with the ViewModel layout and its container choice, then apply component classes for visual presentation. For layout and CSS techniques beyond the component classes, see Documentation:UI&Styling.
Use the stylesheet for component-specific recipes
Documentation:MDriven Stylesheet is the reference for the available modifier classes and recipes, including:
- button forms and colours;
- icons and special buttons;
- information elements and removable information banners;
- tables, reporting states, cards, lists, and search boxes.
For example, the documented removable information-banner recipe uses a GroupBox with tk-info-banner, static text, and a remove action with tk-remove-btn. It also uses a Boolean variable to control whether the banner is visible. Follow that recipe when you need a dismissible message rather than constructing a visually similar component with unrelated classes.