useSettings
Overview
The useSettings()
hook is a React hook that allows you to access the settings of your app. This hook enables you to modify the settings of your app and also update distinct settings to different pages within it.
Values
The useSettings()
hook provides the following variables, allowing you to customize the settings of your app.
Value | Type | Description |
---|---|---|
settings | Settings | The settings of your app. |
isSettingsChanged | boolean | Indicates whether the initial settings changed. |
updateSettings | (settings: Partial<Settings>, options?: UpdateSettingsOptions) => void | A function that updates the settings of your app. |
resetSettings | () => void | A function that reset the settings to the initial settings. |
updatePageSettings | (settings: Partial<Settings>) => () => void | A function that updates the settings of a specific page. |
export type Settings = {
mode?: Mode;
skin?: Skin;
semiDark?: boolean;
layout?: Layout;
navbarContentWidth?: LayoutComponentWidth;
contentWidth?: LayoutComponentWidth;
footerContentWidth?: LayoutComponentWidth;
primaryColor?: string;
};
type UpdateSettingsOptions = {
updateCookie?: boolean;
};
The updateCookie
prop allows you to update the settings of your app in the browser's cookies. By default, this prop is set to true
.
Usage
To utilize the useSettings()
hook, please refer to the following examples:
Mode
The mode
property in the Settings type is used to define the visual mode of your application. It can be used to switch between different mode, such as a light
, dark
, or a system
mode defined within your application.
Here's an example of how you can use the mode
property:
Skin
The skin
property in the Settings type is used to define the visual skin of your application. It can be used to switch between different skins, such as default
and bordered
.
Here's an example of how you can use the skin
property:
SemiDark
The semiDark
property in the Settings type is used to define a semi-dark
mode in your application.
Here's an example of how you can use the semiDark
property:
Layout
The layout
property in the Settings type is used to define the layout structure of your application. It can be used to switch between different layout styles such as vertical
, horizontal
, and collapsed
.
Here's an example of how you can use the layout
property:
navbarContentWidth
The navbarContentWidth
property in the Settings type is used to define the width of the navigation bar content in your application. It can be used to switch between different width styles such as compact
and wide
.
Here's an example of how you can use the navbarContentWidth
property:
ContentWidth
The contentWidth
property in the Settings type is used to define the width of the main content area in your application. It can be used to switch between different width styles such as compact
and wide
.
Here's an example of how you can use the contentWidth
property:
footerContentWidth
The footerContentWidth
property in the Settings type is used to define the width of the footer content in your application. It can be used to switch between different width styles such as compact
and wide
.
Here's an example of how you can use the footerContentWidth
property:
primaryColor
The primaryColor
property in the Settings type is used to define the primary color of your application. It can be used to switch between different primary colors defined within your application.
Here's an example of how you can use the primaryColor
property:
Change/Reset SettingsMode
In your application, you may need to change or reset the settings properties based on user interactions or other requirements. This can be achieved using the resetSettings function provided by the useSettings hook.
Here's an example of how you can change a setting:
updatePageSettings
In your application, you may need to update the settings of a specific page. This can be achieved using the updatePageSettings
function provided by the useSettings
hook.
note that this settings will be applied to the specific page only and not the whole app.
When using Material-UI's theme
object to apply colors in your components along with updatePageSettings
for a particular page, you might encounter a class mismatch issue between the server and the client. This happens when the server-side rendered markup doesn't match the client-side rendered markup, often due to differences in the theme settings.
This issue can be particularly prevalent on pages where users have specific settings that affect the theme, as these settings might not be taken into account during server-side rendering, leading to a mismatch when the client-side rendering takes place.
To avoid this issue, it's recommended to use CSS variables for colors instead of using the theme
object. For example, instead of using theme.palette.primary.main
, you can use 'var(--mui-palette-primary-main)'
. This way the className
will be consistent between server-side and client-side rendering
Here's an example of how you can change a setting in a particular page: